integrations: state explicitly that you must create the notification stream.

(imported from commit aedf0e27294c41298e184787c1803217b6d90b8b)

templates/zerver/integrations.html

@@ -61,7 +61,12 @@
     {#--------------------------------------------------------------------#}
     <div id="beanstalk" class="integration">
       <h4>Beanstalk</h4>
-     <p>Zulip supports both SVN and Git notifications from Beanstalk. In the beanstalk web application, go to the Setup page, and choose the Integrations tab.
+     <p>Zulip supports both SVN and Git notifications from Beanstalk.</p>
+
+     <p>First, create the stream <code>commits</code> and subscribe all
+     interested parties to this stream.</p>
+
+     <p>Next, in the Beanstalk web application, go to the Setup page and choose the Integrations tab.
      Choose the <code>Webhooks</code> integration from the list presented. Make sure to replace the <code>@</code> in the bot's email address with <code>%40</code>,
      as Beanstalk's website will incorrectly refuse to parse a username containing a <code>@</code>.</p>
 
@@ -79,17 +84,26 @@
     {#--------------------------------------------------------------------#}
     <div id="bitbucket" class="integration">
       <h4>Bitbucket</h4>
-     <p>Zulip supports both Git and Mercural notifications from Bitbucket. From your repository's web page, go to the Administraion page, and choose Hooks on the left-hand side.
+
+     <p>Zulip supports both Git and Mercural notifications from Bitbucket.</p>
+
+     <p>First, create the stream you'd like to use for Bitbucket notifications,
+     and subscribe all interested parties to this stream. The integration will
+     use the default stream <code>commits</code> if no stream is supplied in the
+     hook; you still need to create the stream even if you are using this
+     default.</p>
+
+     <p>Next, from your repository's web page, go to the Administraion page and choose Hooks on the left-hand side.
      Choose the <code>POST</code> hook from the list presented and click "Add hook."   Make sure to replace the <code>@</code> in the bot's email address with <code>%40</code>,
      as Bitbucket will not execute the hook if the username contains a <code>@</code>.</p>
 
       <p>In the URL field, enter <code>https://bot_email:bot_api_key@api.zulip.com/v1/external/bitbucket</code>:</p>
       <img class="screenshot" src="/static/images/integrations/bitbucket/001.png">
 
-      <p>By default, notifications are sent to
+      <p>By default, notifications are sent to the <code>commits</code> stream.
-      the <code>commits</code> stream.  To send notifications to a
+      To send notifications to a different stream,
-      different stream, append <code style="white-space: nowrap;">?stream=stream_name</code> to
+      append <code style="white-space: nowrap;">?stream=stream_name</code> to
-      the URL.  The stream must already exist.</p>
+      the URL.</p>
 
       <p><b>Congratulations! You're done!</b><br /> Whenever you push code to your repository,
         you'll get an automated notification that looks like this:</p>
@@ -148,6 +162,12 @@
       <p>First, download and install our <a href="/api">Python
       bindings and example scripts</a> on your Git server.</p>
 
+      <p>Next, create the stream you'd like to use for Git notifications, and
+      subscribe all interested parties to this stream. The integration will use
+      the default stream <code>commits</code> if no stream is supplied in the
+      hook; you still need to create the stream even if you are using this
+      default.</p>
+
       <p>Next, open <code>integrations/git/zulip_git_config.py</code>
       in your favorite editor, and change the following lines to
       specify the email address and API key for your Git bot:</p>
@@ -189,7 +209,14 @@
 {#--------------------------------------------------------------------#}
     <div id="github" class="integration">
       <h4>GitHub</h4>
-      <p>First, go to your repository page and click "Settings":</p>
+
+      <p>First, create the stream you'd like to use for GitHub notifications,
+      and subscribe all interested parties to this stream. The integration will
+      use the default stream <code>commits</code> if no stream is supplied in
+      the hook; you still need to create the stream even if you are using this
+      default.</p>
+
+      <p>Next, go to your repository page and click "Settings":</p>
       <img src="/static/images/integrations/github/001.png">
 
       <p>From there, select "Service Hooks":</p>
@@ -213,6 +240,10 @@ following, to the stream <code>commits</code> with a subject that matches the re
     <div id="jenkins" class="integration">
       <h4>Jenkins (or Hudson)</h4>
 
+      <p>First, create the stream you'd like to use for Jenkins or Hudson
+      notifications, and subscribe all interested parties to this stream. We
+      recommend the name <code>jenkins</code> or <code>hudson</code>.</p>
+
       <p><strong>Install the plugin</strong><br />
       Install the "Humbug" plugin by going to <code>Manage Jenkins
       > Manage Plugins > Available</code>, typing in "Humbug", and
@@ -224,8 +255,7 @@ following, to the stream <code>commits</code> with a subject that matches the re
       is installed, configure it by going to <code>Manage Jenkins >
       Configure System</code>. Scroll to the section labeled "Humbug
       Notification Settings", and specify your bot's email address,
-      API key, where you'd like your notification messages to go (we
+      API key, the stream receiving the notifications, and whether you'd
-      recommend the stream <code>jenkins</code>), and whether you'd
       like a notification on every build, or only when the build fails
       (Smart Notification).</p>
 
@@ -262,6 +292,11 @@ following, to the stream <code>commits</code> with a subject that matches the re
 {#--------------------------------------------------------------------#}
    <div id="jira" class="integration">
       <h4>JIRA</h4>
+
+      <p>First, create the stream you'd like to use for JIRA notifications, and
+      subscribe all interested parties to this stream. We recommend the
+      name <code>jira</code>.</p>
+
       <h5>Webhook mechanism</h5>
       If you are running JIRA version 5.2 or greater, or if you are using the hosted JIRA provided
       by Atlassian, you can use the built in web-hook support to connect to Zulip. If you are not
@@ -278,7 +313,7 @@ following, to the stream <code>commits</code> with a subject that matches the re
 
       <p>where <code>api_key</code> is the API key of your Zulip bot,
       and <code>stream</code> is the stream name you want the
-      notifications sent to. The stream must already exist.</p>
+      notifications sent to.</p>
 
       <p>Next, go back to Zulip and set up a stream called "jira," if it does not already exist.
       (If you prefer your JIRA notifications to go to a stream other than "jira," then change the URL above to match it.)</p>
@@ -293,8 +328,13 @@ following, to the stream <code>commits</code> with a subject that matches the re
 {#--------------------------------------------------------------------#}
    <div id="jira-plugin" class="integration">
       <h4>JIRA</h4>
+
+      <p>First, create the stream you'd like to use for JIRA notifications, and
+      subscribe all interested parties to this stream. We recommend the
+      name <code>jira</code>.</p>
+
       <h5>Plugin mechanism</h5>
-      First, download and install our <a href="/api">Python bindings and example scripts</a>.
+      Next, download and install our <a href="/api">Python bindings and example scripts</a>.
       <p><b>Plugin Installation</b></p>
         The JIRA integration plugin requires two JIRA plugins. Please install
         the following plugins using the Universal Plugin Manager in your JIRA
@@ -334,7 +374,14 @@ following, to the stream <code>commits</code> with a subject that matches the re
 {#--------------------------------------------------------------------#}
     <div id="nagios" class="integration">
       <h4>Nagios</h4>
-      <p>First, download and install our <a href="/api">Python
+
+      <p>First, create the stream you'd like to use for Nagios notifications,
+      and subscribe all interested parties to this stream. The integration will
+      use the default stream <code>nagios</code> if no stream is supplied in the
+      configuration; you still need to create the stream even if you are using
+      this default.</p>
+
+      <p>Next, download and install our <a href="/api">Python
       bindings and example scripts</a> on your Nagios server.</p>
 
       <p>Next, open <code>integrations/nagios/zuliprc.example</code>
@@ -398,14 +445,23 @@ key=NAGIOS_BOT_API_KEY
 {#--------------------------------------------------------------------#}
     <div id="pivotal" class="integration">
       <h4>Pivotal Tracker</h4>
-     <p>Zulip supports Pivotal Tracker integration and can notify you of changes to the stories in your Pivotal Tracker project. In the Settings page
-      for your project, choose the Integrations tab. Scroll down to the <code>Activity Web Hook</code> section, and enter the following url:</p>
 
-x      <p><code>https://api.zulip.com/v1/external/pivotal?api_key=abcdefgh&amp;stream=pivotal</code></p>
+      <p>Zulip supports Pivotal Tracker integration and can notify you of changes
+      to the stories in your Pivotal Tracker project.</p>
+
+      <p>First, create the stream you'd like to use for Pivotal Tracker
+      notifications, and subscribe all interested parties to this stream. We
+      recommend the name <code>pivotal</code>.</p>
+
+      <p>Next, in the Settings page for your project, choose the Integrations
+      tab. Scroll down to the <code>Activity Web Hook</code> section, and enter
+      the following url:</p>
+
+      <p><code>https://api.zulip.com/v1/external/pivotal?api_key=abcdefgh&amp;stream=pivotal</code></p>
 
       <p>where <code>api_key</code> is the API key of your Zulip bot,
       and <code>stream</code> is the stream name you want the
-      notifications sent to. The stream must already exist.</p>
+      notifications sent to.</p>
 
       <img class="screenshot" src="/static/images/integrations/pivotal/001.png">
 
@@ -419,16 +475,22 @@ x      <p><code>https://api.zulip.com/v1/external/pivotal?api_key=abcdefgh&amp;s
     <div id="newrelic" class="integration">
      <h4>New Relic</h4>
 
-     <p>New Relic can send messages to a Zulip stream for alerts and deploys.
+      <p>New Relic can send messages to a Zulip stream for alerts and
-     In your New Relic Account Settings page, click "Integrations", then
+      deploys.</p>
-     "Alerting notifications". On the "Webhook" tab, enter the following
+
-     webhook URL:</p>
+      <p>First, create the stream you'd like to use for New Relic
+      notifications, and subscribe all interested parties to this stream. We
+      recommend the name <code>newrelic</code>.</p>
+
+      <p>Next, in your New Relic Account Settings page, click
+      "Integrations", then "Alerting notifications". On the "Webhook"
+      tab, enter the following webhook URL:</p>
 
       <p><code>https://api.zulip.com/v1/external/newrelic?api_key=abcdefgh&amp;stream=newrelic</code></p>
 
       <p>where <code>api_key</code> is the API key of your Zulip bot,
       and <code>stream</code> is the stream name you want the
-      notifications sent to. The stream must already exist.</p>
+      notifications sent to.</p>
 
       <img class="screenshot" src="/static/images/integrations/newrelic/001.png">
 
@@ -446,6 +508,14 @@ x      <p><code>https://api.zulip.com/v1/external/pivotal?api_key=abcdefgh&amp;s
       <p>It is easy to send Zulips on SVN commits, by configuring a post-commit
       hook. To do this:</p>
 
+      <p>First, create the stream you'd like to use for SVN commit
+      notifications, and subscribe all interested parties to this stream. The
+      integration will use the default stream <code>commits</code> if no stream
+      is supplied in the hook; you still need to create the stream even if you
+      are using this default.</p>
+
+      <p>Then:</p>
+
       <ol>
         <li>Download and install our <a href="/api">Python bindings</a> on the
         server where the SVN repository lives.</li>
@@ -480,7 +550,14 @@ x      <p><code>https://api.zulip.com/v1/external/pivotal?api_key=abcdefgh&amp;s
 {#--------------------------------------------------------------------#}
     <div id="trac" class="integration">
       <h4>Trac</h4>
-      <p>First, download and install our <a href="/api">Python
+
+      <p>First, create the stream you'd like to use for Trac notifications, and
+      subscribe all interested parties to this stream. The integration will use
+      the default stream <code>trac</code> if no stream is supplied in the
+      hook; you still need to create the stream even if you are using this
+      default.</p>
+
+      <p>Next, download and install our <a href="/api">Python
       bindings and example scripts</a> on your Trac server.</p>
 
       <p>Next, open <code>integrations/trac/zulip_trac_config.py</code> in
@@ -527,7 +604,12 @@ x      <p><code>https://api.zulip.com/v1/external/pivotal?api_key=abcdefgh&amp;s
 {#--------------------------------------------------------------------#}
     <div id="trello" class="integration">
       <h4>Trello</h4>
-      <p>Download a copy
+
+      <p>First, create the stream you'd like to use for Trello notifications,
+      and subscribe all interested parties to this stream. We recommend the
+      name <code>trello</code>.</p>
+
+      <p>Next, download a copy
       of <a href="https://github.com/nathanlws/trello-to-zulip">trello-to-zulip</a>
       and follow the instructions in <code>README.md</code>. When you
       make changes in Trello, they will be reflected in Zulip: