search

tenfourty / chatbot

a hubot chatbot
2 stars 5 forks source link

readme

chatbot Build Status

chatbot is a bot for Apigee's slack instance built on the Hubot (pronounced hew-bot) framework. It was initially generated by Jeremy Brown and has been setup to run on OpenShift and talks to Slack via the slack-irc gateway so it appears as a real person.

How to Contribute

All contributions are more than welcome and easy!

  1. fork this repository
  2. work locally on your contribution, see running chatbot locally below for how to run it on your own machine
  3. check your changes in and push to your repository
  4. submit a pull request back to tenfourty/chatbot
  5. one of the admins will review your pull request and accept it
  6. once your pull request has been accepted your code will be built again by travis-ci, this time from the master branch
    • you can see your build happening in travis-ci
  7. once your build is done it will be deployed to dev_chatbot, which is running here - http://dev.apigee-chatbot.me/
  8. dev_chatbot will appear in the following rooms in slack:

    • general (no way to turn this off, but it should be muted)

    • chatbot-dev

    • chatbot-test

    • and of course you can private message it as well
  9. do any live testing of dev_chatbot but please try to only use the #chatbot-test room as we don't want to mess up the other rooms.
  10. once you are happy with how it is working get one of the chatbot GitHub admins to tag the new version in the GitHub repo, this will trigger a new build in travis-ci that will deploy to the main chatbot that is sitting in all the rooms.

This is the short version but you might want to check out the following sections:

Running chatbot locally

You can test your hubot by running the following, however some plugins will not behave as expected unless the environment variables they rely upon have been set.

You can start chatbot locally by running:

% bin/hubot

You'll see some start up output and a prompt:

[Sat Feb 28 2015 12:38:27 GMT+0000 (GMT)] INFO Using default redis on localhost:6379
chatbot>

Then you can interact with chatbot by typing chatbot help.

chatbot> chatbot help
chatbot animate me <query> - The same thing as `image me`, except adds [snip]
chatbot help - Displays all of the help commands that chatbot knows about.
...

Configuration

A few scripts (including some installed by default) require environment variables to be set as a simple form of configuration.

Each script should have a commented header which contains a "Configuration" section that explains which values it requires to be placed in which variable. When you have lots of scripts installed this process can be quite labour intensive. The following shell command can be used as a stop gap until an easier way to do this has been implemented.

grep -o 'hubot-[a-z0-9_-]\+' external-scripts.json | \
  xargs -n1 -I {} sh -c 'sed -n "/^# Configuration/,/^#$/ s/^/{} /p" \
      $(find node_modules/{}/ -name "*.coffee")' | \
    awk -F '#' '{ printf "%-25s %s\n", $1, $2 }'

How to set environment variables will be specific to your operating system. Rather than recreate the various methods and best practices in achieving this, it's suggested that you search for a dedicated guide focused on your OS.

Secrets

TODO - document secrets. speak to an admin for now... will update this asap.

Scripting

An example script is included at scripts/example.coffee, so check it out to get started, along with the Scripting Guide.

For many common tasks, there's a good chance someone has already one to do just the thing.

external-scripts

There will inevitably be functionality that everyone will want. Instead of writing it yourself, you can use existing plugins.

Hubot is able to load plugins from third-party npm packages. This is the recommended way to add functionality to your hubot. You can get a list of available hubot plugins on npmjs.com or by using npm search:

% npm search hubot-scripts panda
NAME             DESCRIPTION                        AUTHOR DATE       VERSION KEYWORDS
hubot-pandapanda a hubot script for panda responses =missu 2014-11-30 0.9.2   hubot hubot-scripts panda
...

To use a package, check the package's documentation, but in general it is:

  1. Use npm install --save to add the package to package.json and install it
  2. Add the package name to external-scripts.json as a double quoted string

You can review external-scripts.json to see what is included by default.

Advanced Usage

It is also possible to define external-scripts.json as an object to explicitly specify which scripts from a package should be included. The example below, for example, will only activate two of the six available scripts inside the hubot-fun plugin, but all four of those in hubot-auto-deploy.

{
  "hubot-fun": [
    "crazy",
    "thanks"
  ],
  "hubot-auto-deploy": "*"
}

Be aware that not all plugins support this usage and will typically fallback to including all scripts.

hubot-scripts

Before hubot plugin packages were adopted, most plugins were held in the hubot-scripts package. Some of these plugins have yet to be migrated to their own packages. They can still be used but the setup is a bit different.

To enable scripts from the hubot-scripts package, add the script name with extension as a double quoted string to the hubot-scripts.json file in this repo.