Add developer documentation for bots #2766

roberthoenig · 2016-12-18T15:16:46Z

Add a documentation for the new experimental bots support of Zulip.
Describe how to deploy and develop bots, as well as common errors and their solutions.
This is my work for the GCI task: https://codein.withgoogle.com/dashboard/task-instances/5546362475118592/
The Zulip discussion on it can be found here: https://chat.zulip.org/#narrow/stream/GCI.20tasks/topic/create.20documentation.20for.20bots.20development

smarx · 2016-12-18T15:16:46Z

Automated message from Dropbox CLA bot

@derAnfaenger, it looks like you've already signed the Dropbox CLA. Thanks!

showell · 2016-12-18T16:59:16Z

docs/bots-guide.md

@@ -0,0 +1,188 @@
+# Developing bots
+**This feature is still experimental**
+Bots are a new system in Zulip, allowing developers to react to messages.


Say "The contrib_bots system is a new part of Zulip that allows bot developers to write a large class of bots by simply reacting to message."

showell · 2016-12-18T16:59:55Z

docs/bots-guide.md

+Contributions to this guide are very welcome, so if you run into any
+issues following these instructions or come up with any tips or tools
+that help writing integration, please email
+zulip-devel@googlegroups.com, open an issue, or submit a pull request


Tell them instead to go to chat.zulip.org.

I just noticed that I didn't change the "writing integration" part, will do so as well.

showell · 2016-12-18T17:00:48Z

docs/bots-guide.md

+*  A new bot should appear in the *Your Bots* panel.
+4. Add the bot's configuration file on your Zulip server.
+* In the *Your Bots* panel, click on the green icon to download its configuration file *.zuliprc* (the structure of this file is explained [here](#configuration-file)
+*  Copy the file to a destination of your choice on your Zulip server, e.g. to `~/.zuliprc`


e.g. to ~/.zuliprc or ~/zuliprc-test.

showell · 2016-12-18T17:01:22Z

docs/bots-guide.md

+4. Add the bot's configuration file on your Zulip server.
+* In the *Your Bots* panel, click on the green icon to download its configuration file *.zuliprc* (the structure of this file is explained [here](#configuration-file)
+*  Copy the file to a destination of your choice on your Zulip server, e.g. to `~/.zuliprc`
+5. Subscribe the bot to the streams where you want to use it.


Subscribe the bot to any streams that the bot needs to read message from or write message to.

showell · 2016-12-18T17:01:50Z

docs/bots-guide.md

+* In the *Your Bots* panel, click on the green icon to download its configuration file *.zuliprc* (the structure of this file is explained [here](#configuration-file)
+*  Copy the file to a destination of your choice on your Zulip server, e.g. to `~/.zuliprc`
+5. Subscribe the bot to the streams where you want to use it.
+* By default, the bot *does not intercept/send messages* on any stream.


Omit this line for now. ^^^

Okay, will do, but why?

showell · 2016-12-18T17:02:20Z

docs/bots-guide.md

+*  Copy the file to a destination of your choice on your Zulip server, e.g. to `~/.zuliprc`
+5. Subscribe the bot to the streams where you want to use it.
+* By default, the bot *does not intercept/send messages* on any stream.
+* To change that, navigate to *Manage Streams*. Select a stream and add your bot by its email address (the address you assigned in step 2).


To subscribe your bot to streams,...

showell · 2016-12-18T17:03:16Z

docs/bots-guide.md

+*  On your Zulip server, navigate to `~/zulip/contrib_bots/`
+* Run `python run.py ~/zulip/contrib_bots/<my-bot>.py --config-file ~/.zuliprc`
+* Congrats! Now, your bot should be ready to test on the streams you subscribed it to.
+


Describe what the output looks like when you start a bot. It shows usage then it shows HTTP connection stuff.

showell · 2016-12-18T17:05:08Z

docs/bots-guide.md

+* email - the email address of the bot, e.g. `some-bot@zulip.com`
+* site - your development environment URL. If you are working on a development environment hosted on your computer, use `localhost:9991`
+##Common problems
+* I modified my bot's code, yet the changes don't seem to have an effect.


A couple other problems are you forgot to store the host or you didn't create your API config correctly.

showell · 2016-12-18T17:06:09Z

This is an excellent start @derAnfaenger! I added a lot of comments, but the overall structure here looks great, and this will be really helpful documentation. Thanks!

showell · 2016-12-18T21:41:45Z

docs/bots-guide.md

@@ -0,0 +1,192 @@
+# Developing bots
+**This feature is still experimental**
+The contrib_bots system is a new part of Zulip that allows bot developers to write a large class of bots by simply reacting to message.


s/message/messages/

showell · 2016-12-18T21:44:50Z

docs/bots-guide.md

+ * Run `python run.py ~/zulip/contrib_bots/<my-bot>.py --config-file ~/.zuliprc
+ * Check the output of the command. It should start with the text the `usage` function returns, followed by logging output similar to this:
+
+>INFO:root:starting message handling...


Can you put this inside of triple backticks?

showell · 2016-12-18T21:45:32Z

docs/bots-guide.md

+    def usage(self):
+        return '''Your description of the bot'''
+
+    def triage_message(self, message):


Just a heads up that we may add another parameter here called "client." No need to address this now.

showell · 2016-12-18T21:46:20Z

docs/bots-guide.md

+Is called by the system when a message was sent.
+#### Arguments
+* self - the instance the method is called on.
+* message - an object containing information about the message, e.g.


s/an object/a dictionary/

showell · 2016-12-18T21:47:43Z

docs/bots-guide.md

+Is called when `triage_message` returns true, handles user message.
+#### Arguments
+* self - the instance the method is called on.
+* message - an object containing information about the message, e.g.


We may want to de-duplicate this by saying something like "* message - a dictionary describing a Zulip message (click [here] to see more about the message fields)

I agree with this. It kind of takes up unnecessary space.

showell · 2016-12-18T21:49:08Z

docs/bots-guide.md

+## Common problems
+* I modified my bot's code, yet the changes don't seem to have an effect.
+ * Assure that you restarted the `run.py` script.
+ * Assure that your API config file is correct (download the config file from the server)


I think this should be a separate bullet--"My program won't start"--instead of being a sub-bullet of "I modified my bot's code...".

lonerz · 2016-12-18T21:53:05Z

docs/bots-guide.md

+
+Contributions to this guide are very welcome, so if you run into any
+issues following these instructions or come up with any tips or tools
+that help writing bots, please visit chat.zulip.org, open an issue, or submit a pull request


that help with writing bots

lonerz · 2016-12-18T21:56:25Z

docs/bots-guide.md

+4. Add the bot's configuration file on your Zulip server.
+ * In the *Your Bots* panel, click on the green icon to download its configuration file *.zuliprc* (the structure of this file is explained [here](#configuration-file)
+ * Copy the file to a destination of your choice on your Zulip server, e.g. to `~/.zuliprc`or ~/zuliprc-test.
+5. Subscribe the bot to any streams that the bot needs to read message from or write message to.55


Not sure if it is "any streams" or "any stream". Also, typo at the end "to.55"

lonerz · 2016-12-18T21:57:05Z

docs/bots-guide.md

+ * In the *Your Bots* panel, click on the green icon to download its configuration file *.zuliprc* (the structure of this file is explained [here](#configuration-file)
+ * Copy the file to a destination of your choice on your Zulip server, e.g. to `~/.zuliprc`or ~/zuliprc-test.
+5. Subscribe the bot to any streams that the bot needs to read message from or write message to.55
+ * To subscribe your bot to streams, navigate to *Manage Streams*. Select a stream and add your bot by its email address (the address you assigned in step 2).


You didn't assign any address in step 2. I think you mean step 3?

trueskawka

Hi @derAnfaenger!

Thanks for working on this, it looks great :)

I've had a lot of comments, but most of them were on Markdown rendering - I've been checking it while also looking at a preview of your document. Could you make sure the rendering is appropriate before you ask for your next review? You can preview the document on GitHub or usually in your editor (I'm using Atom to preview my Markdown documents).

Thanks!

trueskawka · 2016-12-18T21:40:58Z

docs/bots-guide.md

+With bots, you *cannot*
+
+* modify an intercepted message (you have to send a new message)
+* send messages in the name of other users


I'd say "on behalf of other users".

trueskawka · 2016-12-18T21:42:33Z

docs/bots-guide.md

@@ -0,0 +1,192 @@
+# Developing bots
+**This feature is still experimental**
+The contrib_bots system is a new part of Zulip that allows bot developers to write a large class of bots by simply reacting to message.


A general comment to improve readability for devs - could you try to keep the line length at 80 characters? If you make just one line break, Markdown won't pick it up as a new paragraph and it'll be easier to read on different setups.

trueskawka · 2016-12-18T21:43:28Z

docs/bots-guide.md

+
+Contributions to this guide are very welcome, so if you run into any
+issues following these instructions or come up with any tips or tools
+that help writing bots, please visit chat.zulip.org, open an issue, or submit a pull request


Could you write chat.zulip.org as a link?

trueskawka · 2016-12-18T21:44:11Z

docs/bots-guide.md

+## How to deploy a bot
+This guide will show you how to deploy a bot on your running Zulip server. It presumes that you already have a fully implemented `<my-bot>.py` bot and now want to try it out.
+
+1. Copy your bot `<my-bot>.py` to `~/zulip/contrib_bots/lib/`.


I'd add line breaks after each point and it's subpoints, to improve readability.

trueskawka · 2016-12-18T21:44:41Z

docs/bots-guide.md

+
+1. Copy your bot `<my-bot>.py` to `~/zulip/contrib_bots/lib/`.
+ * This is the place where all Zulip bots are stored.
+ * You can also test out already existing bots in this directory.


A bit of rephrasing You can also test out bots that already exist in this directory.

trueskawka · 2016-12-18T22:09:07Z

docs/bots-guide.md

+    ))
+ ```
+
+ ###Configuration file


This indentation is also off, maybe because there is a missing whitespace after ###?

trueskawka · 2016-12-18T22:11:31Z

docs/bots-guide.md

+email=<email>
+site=<dev-url>
+ ```
+* key - the API key you created for the bot. This is how Zulip knows the request is from an authorized user.


Again, a sentence here looks a bit awkward, I'd use ; and no full stops.

trueskawka · 2016-12-18T22:11:49Z

docs/bots-guide.md

+ ```
+* key - the API key you created for the bot. This is how Zulip knows the request is from an authorized user.
+* email - the email address of the bot, e.g. `some-bot@zulip.com`
+* site - your development environment URL. If you are working on a development environment hosted on your computer, use `localhost:9991`


Same as line 184

trueskawka · 2016-12-18T22:12:29Z

docs/bots-guide.md

+* key - the API key you created for the bot. This is how Zulip knows the request is from an authorized user.
+* email - the email address of the bot, e.g. `some-bot@zulip.com`
+* site - your development environment URL. If you are working on a development environment hosted on your computer, use `localhost:9991`
+## Common problems


The indentation and rendering here are off because of missing whitespace before this line.

trueskawka · 2016-12-18T22:13:56Z

docs/bots-guide.md

+ * Assure that you restarted the `run.py` script.
+ * Assure that your API config file is correct (download the config file from the server)
+* My bot works only on some streams.
+ * Subscribe your bot to other streams, as described [here](#how-to-deploy-a-bot).


I think My bot doesn't work is by far the most common problem.

I'd say check API keys, check server address and make sure your bot is subscribed to the streams you're using it in are the most basic answers.

synicalsyntax · 2016-12-19T22:52:14Z

docs/bots-guide.md

@@ -0,0 +1,230 @@
+# Developing bots
+**This feature is still experimental**
+The contrib_bots system is a new part of Zulip that allows


You should insert a new line break here.

synicalsyntax · 2016-12-19T22:54:51Z

docs/bots-guide.md

+
+### usage
+*usage(self)*
+Is called to retrieve information about the bot.


If you want "Is called to retrieve information about the bot." to start on a new line, you need to insert another line break. Same goes for triage_message, handle_message, etc.

showell · 2016-12-19T23:02:37Z

Except for @lonerz and @synicalsyntax, I am asking folks to freeze review on this. This has been pretty heavily worked over, and I'm eager to merge. Once we get it merged, folks can submit follow-up PRs to clean some minor stuff like formatting issues, etc.

lonerz · 2016-12-19T22:48:10Z

docs/bots-guide.md

@@ -0,0 +1,230 @@
+# Developing bots
+**This feature is still experimental**


Change to This feature is still experimental. (period)

lonerz · 2016-12-19T22:51:43Z

docs/bots-guide.md

+
+2. Run your Zulip server. Bots can only be deployed on running systems.
+
+3. Register a new bot at your Zulip server's web interface.


Register a new bot on your Zulip...

lonerz · 2016-12-19T22:52:18Z

docs/bots-guide.md

+4. Add the bot's configuration file on your Zulip server.
+
+ * In the *Your Bots* panel, click on the green icon to download its configuration file *.zuliprc*
+ (the structure of this file is explained [here](#configuration-file)


Missing a period at the end of this sentence.

lonerz · 2016-12-19T22:53:20Z

docs/bots-guide.md

+
+ * Copy the file to a destination of your choice on your Zulip server, e.g. to `~/.zuliprc` or `~/zuliprc-test`.
+
+5. Subscribe the bot to any streams that the bot needs to read messages from or write messages to.


I think "subscribe the bot to the streams" sounds less ambiguous

lonerz · 2016-12-19T22:55:19Z

docs/bots-guide.md

+ followed by logging output similar to this:
+```
+INFO:root:starting message handling...
+INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): localhost


Is there some way to get both INFO lines to be indented correctly?

lonerz · 2016-12-19T23:01:09Z

docs/bots-guide.md

+### handle_message
+*handle_message(self, message, client)*
+Is called when `triage_message` returns true, handles user message.
+


Again, same thing here, like usage.

lonerz · 2016-12-19T23:01:36Z

docs/bots-guide.md

+#### Arguments
+* self - the instance the method is called on.
+
+* message - a dictionary describing a Zulip message (click [here](#triagemessage) to see more about the message fields)


Triage-message link is broken.

lonerz · 2016-12-19T23:01:50Z

docs/bots-guide.md

+* client - used to interact with the server, e.g. to send a message
+ * use client.send_message(message) to send a message
+
+* state_handler - used to save states/information of the bot**beta**


missing space between bot and beta.

lonerz · 2016-12-19T23:02:25Z

docs/bots-guide.md

+ site=<dev-url>
+ ```
+
+* key - the API key you created for the bot; this is how Zulip knows the request is from an authorized user.


do you actually create the API key? Don't you receive an API key for the bot?

lonerz · 2016-12-19T23:02:58Z

docs/bots-guide.md

+ * Assure that you restarted the `run.py` script.
+
+* My bot won't start
+ * Assure that your API config file is correct (download the config file from the server)


Missing a period at the end of sentence.

showell · 2016-12-20T00:29:50Z

merged, thanks, @derAnfaenger !

showell reviewed Dec 18, 2016

View reviewed changes

roberthoenig force-pushed the documentation-bots branch 4 times, most recently from c807fe5 to b4cd8ed Compare December 18, 2016 21:09

showell reviewed Dec 18, 2016

View reviewed changes

lonerz reviewed Dec 18, 2016

View reviewed changes

trueskawka reviewed Dec 18, 2016

View reviewed changes

roberthoenig force-pushed the documentation-bots branch 3 times, most recently from 39fed26 to 56b9f58 Compare December 19, 2016 22:42

synicalsyntax reviewed Dec 19, 2016

View reviewed changes

lonerz reviewed Dec 19, 2016

View reviewed changes

Add developer documentation for bots

75f988a

roberthoenig force-pushed the documentation-bots branch from 56b9f58 to 75f988a Compare December 19, 2016 23:40

showell merged commit 63e1ca0 into zulip:master Dec 20, 2016

roberthoenig deleted the documentation-bots branch December 20, 2016 11:29

		@@ -0,0 +1,230 @@
		# Developing bots
		This feature is still experimental


		2. Run your Zulip server. Bots can only be deployed on running systems.

		3. Register a new bot at your Zulip server's web interface.


		* Copy the file to a destination of your choice on your Zulip server, e.g. to `~/.zuliprc` or `~/zuliprc-test`.

		5. Subscribe the bot to any streams that the bot needs to read messages from or write messages to.

Add developer documentation for bots #2766

Add developer documentation for bots #2766

Conversation

roberthoenig commented Dec 18, 2016

smarx commented Dec 18, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

showell commented Dec 18, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trueskawka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

synicalsyntax Dec 19, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

showell commented Dec 19, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

showell commented Dec 20, 2016

synicalsyntax Dec 19, 2016 •

edited