hubot 5.0.5 → 5.0.7

package/docs/deploying/bluemix.md

@@ -1,111 +0,0 @@
----
-permalink: /docs/deploying/bluemix/
----
-
-# Deploying to Bluemix
-
-If you've been following along with [Getting Started](../index.md), it's time
-to deploy so you can use it beyond just your local machine.
-[IBM Bluemix](http://bluemix.net) is a way to deploy hubot as an alternative to
-[Heroku](heroku.md). It is built on the open-source project
-[Cloud Foundry](https://www.cloudfoundry.org/), so we'll be using the `cf cli`
-throughout these examples.
-
-Hubot was originally very closely coupled to Heroku, so there are a couple of
-things to clean up first that we don't need or that might get in the way on
-another platform:
-* remove `Procfile` as we'll create the `manifest.yml` that Bluemix needs in a
- moment
-* remove the `hubot-heroku-keepalive` line from `external_scripts.json` and also
- remove the related npm module (it causes errors on other platforms):
-
-  npm uninstall --save hubot-heroku-keepalive
-
-In preparation for working with Bluemix, install the [Cloud Foundry
-CLI](https://github.com/cloudfoundry/cli/releases), and create a [Bluemix
-Account](http://bluemix.net).
-
-First we need to define a `manifest.yml` file in the root directory. The
-contents of the manifest at the bare minimum should look like:
-
-```yml
-applications:
-- name: myVeryOwnHubot
-  command: ./bin/hubot --adapter slack
-  instances: 1
-  memory: 512M
-```
-
-In this example, we're using the slack adapter, if you choose slack as your
-adapter when creating a hubot this will work, otherwise add the `hubot-slack`
-module to your `package.json`.  **Change the name of your hubot in the
-`manifest.yml` file** because otherwise your application will clash with someone
-else's who already deployed an app called this!  There are many more useful
-things you can change about your hubot using the manifest file, so check out
-[these docs](https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html)
-for more information.
-
-You then need to connect your hubot project to Bluemix:
-
-```sh
-$ cd your_hubot_project
-$ cf api https://api.ng.bluemix.net
-$ cf login
-```
-
-Note that the `cf api` command changes per Bluemix region so to deploy somewhere
-other than "US South", replace this api as appropriate.  The `cf login` command
-will prompt you with your login credentials.
-
-Next, we need to set up our environment variables, but we need to create the app
-first.  It won't work properly without the environment variables it needs, so
-we'll first of all use the `--no-start` flag to deploy but not attempt to start
-it.
-
-```sh
-$ cf push NAME_OF_YOUR_HUBOT_APP --no-start
-```
-
-Now the app exists, we can set its environment variables.  To access slack,
-you'll need a slack token from the "Apps and Integrations" page; it's visible
-when you go to create a slackbot.  Copy that token and set it as an environment
-variable called `HUBOT_SLACK_TOKEN`, like this:
-
-```sh
-$ cf set-env NAME_OF_YOUR_HUBOT_APP HUBOT_SLACK_TOKEN TOKEN_VALUE
-```
-
-If you have other environment variables to set, such as configuring the
-`REDIS_URL` for `hubot-redis-brain`, this is a good time to do that.
-
-Finally, we're ready to go!  Deploy "for real" this time:
-
-```sh
-$ cf push NAME_OF_YOUR_HUBOT_APP
-```
-
-You should see your bot connect to slack!
-
-### Further Reading
-
-  - [Deploying Cloud Foundry Apps To Bluemix](https://www.ng.bluemix.net/docs/cfapps/runtimes.html)
-  - [Neploying Node.js Apps to Bluemix](https://www.ng.bluemix.net/docs/starters/nodejs/index.html)
-  - [Setting up your manifest](https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html)
-  - [Understanding the CF CLI](https://www.ng.bluemix.net/docs/cli/reference/cfcommands/index.html)
-  - [Setting up a Build Pipleline in Bluemix](https://www.ng.bluemix.net/docs/#services/DeliveryPipeline/index.html#getstartwithCD)
-
-### Troubleshooting
-
-**Bot doesn't connect**
-
-Check your logs for more information using the command `cf logs YOUR_APP_NAME
---recent`.  If you have NodeJS installed locally, you can also try running the
-bot on your local machine to inspect any output: simply do `bin/hubot` from the
-top level of the project.
-
-**Bot crashes repeatedly**
-
-It is sometimes necessary to to assign more memory to your hubot, depending
-which plugins you are using (if your app crashes with error 137, try increasing
-the memory limit).
-

package/docs/deploying/heroku.md

@@ -1,66 +0,0 @@
----
-permalink: /docs/deploying/heroku/
----
-
-# Deploying to Heroku
-
-If you've been following along with [Getting Started](../index.md), it's time to deploy so you can use it beyond just your local machine.
-[Heroku](http://www.heroku.com/) is an easy and supported way to deploy hubot.
-
-Install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) to start, then follow their '[Getting Started](https://devcenter.heroku.com/articles/heroku-cli#getting-started)' instructions, including logging in the first time:
-
-    % heroku login
-    Enter your Heroku credentials.
-    Email: youremail@example.com
-    Password:
-    Could not find an existing public key.
-    Would you like to generate one? [Yn]
-    Generating new SSH public key.
-    Uploading ssh public key /Users/you/.ssh/id_rsa.pub
-
-Inside your new hubot directory, make sure you've created a git repository, and that your work is committed:
-
-    % git init
-    % git add .
-    % git commit -m "Initial commit"
-
-Then create a Heroku application:
-
-    % heroku create
-    Creating rosemary-britches-123... done, stack is cedar
-    http://rosemary-britches-123.herokuapp.com/ | git@heroku.com:rosemary-britches-123.git
-    Git remote heroku added
-
-Before you deploy the application, you'll need to configure some environment
-variables for hubot to use. The specific variables you'll need depends on which
-[adapter](../adapters.md) and scripts you are using. For Campfire, with no other
-scripts, you'd need to set the following environment variables:
-
-    % heroku config:set HUBOT_CAMPFIRE_ACCOUNT=yourcampfireaccount
-    % heroku config:set HUBOT_CAMPFIRE_TOKEN=yourcampfiretoken
-    % heroku config:set HUBOT_CAMPFIRE_ROOMS=comma,separated,list,of,rooms,to,join
-
-At this point, you are ready to deploy and start chatting. With Heroku, that's a
-git push away:
-
-    % git push heroku main
-
-You'll see some text flying, and eventually some success. You should be able to
-see your bot in your configured chat rooms at this point. If not, you can peek
-at the logs to try to debug:
-
-    % heroku logs
-
-If you make any changes to your hubot, just commit and push them as
-before:
-
-    % git commit -am "Awesome scripts OMG"
-    % git push heroku main
-
-Some scripts needs Redis to work, Heroku offers an addon called [Redis Cloud](https://addons.heroku.com/rediscloud), which has a free plan. To use it:
-
-    % heroku addons:create rediscloud
-
-Note: the free redis plans don't offer any persistence so your hubot will lose all the information when it goes to sleep.
-
-Free dynos on Heroku will [sleep after 30 minutes of inactivity](https://devcenter.heroku.com/articles/dyno-sleeping). That means your hubot would leave the chat room and only rejoin when it does get traffic. This is extremely inconvenient since most interaction is done through chat, and hubot has to be online and in the room to respond to messages. To get around this, you can use the [hubot-heroku-keepalive](https://github.com/hubot-scripts/hubot-heroku-keepalive) script, which will keep your free dyno alive for up to 18 hours/day. If you never want Hubot to sleep, you will need to [upgrade to Heroku's hobby plan](https://www.heroku.com/pricing).

package/docs/deploying/unix.md

@@ -1,72 +0,0 @@
----
-permalink: /docs/deploying/unix/
----
-
-# Deploying to Unix
-
-Because there are so many variations of Linux, and more generally UNIX, it's
-difficult for the hubot team to have canonical documentation for installing and
-deploying it to every version out there. So, this is an attempt to give an
-overview of what's needed to get deploying.
-
-There are 3 primary things to deploying and running hubot:
-
-  * node and npm
-  * a way to get source code updated on the server
-  * a way to start hubot, start it up if it crashes, and restart it when code
-    updates
-
-## node and npm
-
-To start, your UNIX server will need node and npm. Check out the node.js wiki
-for [installing Node.js via package manager](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager), [Building on GNU/Linux and other UNIX](https://github.com/joyent/node/wiki/Installation#building-on-gnulinux-and-other-unix).
-
-## Updating code on the server
-
-The simplest way to update your hubot's code is going to be to have a git
-checkout of your hubot's source code (that you've created during [Getting Started](../index.md), not the [github/hubot repository](http://github.com/github/hubot), and just git pull to get change. This may
-feel a dirty hack, but it works when you are starting out.
-
-If you have a Ruby background, you might be more comfortable using
-[capistrano](https://github.com/capistrano/capistrano).
-
-If you have a [Chef](http://www.chef.io/chef/) background, there's a
-[deploy](https://docs.chef.io/resource_deploy.html) resource for managing
-deployments.
-
-## Starting, stopping, and restarting hubot
-
-Every hubot install has a `bin/hubot` script to handle starting up the hubot.
-You can run this command from your git checkout on the server, but there are some problems you can encounter:
-
-* you disconnect, and hubot dies
-* hubot dies, for any reason, and doesn't start again
-* it doesn't start up at boot automatically
-
-For handling you disconnecting, you can start with running `bin/hubot` in
-[screen session](http://www.gnu.org/software/screen/) or with
-[nohup](http://linux.die.net/man/1/nohup).
-
-For handling hubot dying, and restarting it automatically, you can imagine
-running `bin/hubot` in a
-[bash while loop](http://tldp.org/HOWTO/Bash-Prog-Intro-HOWTO-7.html#ss7.3). But
-really, you probably want some process monitoring using tools like
-[monit](http://mmonit.com/monit/),
-[god](http://godrb.com/),
-[bluepill](https://github.com/arya/bluepill),
-[upstart](http://upstart.ubuntu.com/),
-[runit](http://smarden.org/runit/),
-[systemd](http://freedesktop.org/wiki/Software/systemd/).
-
-For starting at boot, you can create an init script appropriate for your UNIX
-distribution. If you are using one of the process monitoring tools above, make
-sure it boots at startup. See the [examples](https://github.com/github/hubot/tree/main/examples)
-for configuration examples.
-
-## Recommendations
-
-This document has been deliberately light on strong recommendations. At a high
-level though, it's strongly recommended to avoid anything that is overly manual
-and non-repeatable. That would mean using your OS's packages and tools whenever
-possible, and having a proper deploy tool to update hubot, and process
-management to keep hubot running.

package/docs/deploying/windows.md

@@ -1,66 +0,0 @@
----
-permalink: /docs/deploying/windows/
----
-
-# Deploying to Windows
-
-Hasn't been fully tested - YMMV
-
-There are 4 primary steps to deploying and running hubot on a Windows machine:
-
-* node and npm
-* a way to get source code updated on the server
-* setting up environment variables for hubot
-* a way to start hubot, start it up if it crashes, and restart it when code updates
-
-## node and npm
-
-To start, your windows server will need node and npm.
-The best way to do this is with [chocolatey](http://chocolatey.org) using the [nodejs.install](http://chocolatey.org/packages/nodejs.install) package.
-I've found that sometimes the system path variable is not correctly set; ensure you can run node/npm from the command line. If needed set the PATH variable with `set PATH=%PATH%;\"C:\Program Files\nodejs\"`
-
-Your other option is to install directly from [NodeJS](https://nodejs.org/) and run the current download (v0.12.4 as of this documentation). This should set your PATH variables for you.
-
-## Updating code on the server
-
-To get the code on your server, you can follow the instructions at [Getting Started](../index.md) on your local development machine or directly on the server. If you are building locally, push your hubot to GitHub and clone the repo onto your server. Don't clone the normal [github/hubot repository](http://github.com/github/hubot), make sure you're using the Yo Generator to build your own hubot.
-
-## Setting up environment vars
-
-You will want to set up your hubot environment variables on the server where it will run. You can do this by opening an administrative PowerShell and typing the following:
-
-    [Environment]::SetEnvironmentVariable("HUBOT_ADAPTER", "Campfire", "Machine")
-
-This is equivalent to going into the system menu -> selecting advanced system settings -> environment vars and adding a new system variable called HUBOT_ADAPTER with the value of Campfire.
-
-## Starting, stopping, and restarting hubot
-
-Every hubot install has a `bin/hubot` script to handle starting up the hubot.
-You can run this command directly from your hubot folder by typing the following:
-
-    .\bin\hubot –adapter campfire
-
-There are a few issues if you call it manually, though.
-
-* you disconnect, and hubot dies
-* hubot dies, for any reason, and doesn't start again
-* it doesn't start up at boot automatically
-
-To fix this, you will want to create a .ps1 file with whatever name makes you happy that you will call from your hubot directory. There is a copy of this file in the `examples` directory [here](../../examples/hubot-start.ps1). It should contain the following:
-
-    Write-Host "Starting Hubot Watcher"
-    While (1)
-    {
-        Write-Host "Starting Hubot"
-        Start-Process powershell -ArgumentList ".\bin\hubot –adapter slack" -wait
-    }
-
-Remember to allow local unsigned PowerShell scripts if you are using the .ps1 file to run hubot. Run this command in an Administrator PowerShell window.
-
-    Set-ExecutionPolicy RemoteSigned
-
-You can set this .ps1 as scheduled task on boot if you like or some other way to start your process.
-
-## Expanding the documentation
-
-Not yet fleshed out. [Help contribute by submitting a pull request, please?](https://github.com/github/hubot/pull/new/main)

package/docs/deploying.md

@@ -1,11 +0,0 @@
----
-permalink: /docs/deploying/
----
-
-# Deploying
-
-- [Azure](./deploying/azure.md)
-- [Bluemix](./deploying/bluemix.md)
-- [Heroku](./deploying/heroku.md)
-- [Unix](./deploying/unix.md)
-- [Windows](./deploying/windows.md)

package/docs/implementation.md

@@ -1,55 +0,0 @@
----
-title: Implementation Notes
-permalink: /docs/implementation/
----
-
-# Implementation
-
-For the purpose of maintainability, several internal flows are documented here.
-
-## Message Processing
-
-When a new message is received by an adapter, a new Message object is constructed and passed to `robot.receive` (async). `robot.receive` then attempts to execute each Listener in order of registration by calling `listener.call` (async), passing in the Listener Middleware stack. `listener.call` first checks to see if the listener matches (`match` method, sync), and if so, calls `middleware.execute` (async) on the provided middleware.
-
-`middleware.execute` calls each middleware in order of registration. Middleware can either continue forward (call `next`) or abort (call `done`). If all middleware continues, `middleware.execute` calls `next` (the `listener.call` callback). If any middleware aborts, `middleware.execute` calls `done` (which eventually returns to the `robot.receive` callback).
-
-`middleware.execute` `next` returns to `listener.call`, which executes the matched Listener's callback and then calls the `robot.receive` callback.
-
-Inside the `robot.receive` processing loop, `message.done` is checked after each `listener.call`. If the message has been marked as done, `robot.receive` returns. This correctly handles asynchronous middleware, but will not catch an asynchronous set of `message.done` inside the listener callback (which is expected to be synchronous).
-
-If no listener matches the message (distinct from setting `message.done`), a CatchAllMessage is created which wraps the original message. This new message is run through all listeners again testing for a match. `robot.catchAll` creates a special listener that only matches CatchAllMessages.
-
-## Listeners
-
-Listeners are registered using several functions on the `robot` object: `hear`, `respond`, `enter`, `leave`, `topic`, and `catchAll`.
-
-A listener is used via its `call` method, which is responsible for testing to see if a message matches (`match` is an abstract method) and if so, executes the listener's callback.
-
-Listener callbacks are assumed to be synchronous.
-
-## Middleware
-
-There are two primary entry points for middleware:
-
-1. `robot.listenerMiddleware` - registers a new piece of middleware in a global array
-2. `middleware.execute` - executes all registered middleware in order
-
-## Persistence
-
-### Brain
-
-Hubot has a memory exposed as the `robot.brain` object that can be used to store and retrieve data.
-Furthermore, Hubot scripts exist to enable persistence across Hubot restarts.
-`hubot-redis-brain` is such a script and uses a backend Redis server.
-
-By default, the brain contains a list of all users seen by Hubot.
-Therefore, without persistence across restarts, the brain will contain the list of users encountered so far, during the current run of Hubot. On the other hand, with persistence across restarts, the brain will contain all users encountered by Hubot during all of its runs. This list of users can be accessed through `hubot.brain.users()` and other utility methods.
-
-### Datastore
-
-Hubot's optional datastore, exposed as the `robot.datastore` object, provides a more robust persistence model. Compared to the brain, the datastore:
-
-1. Is always (instead of optionally) backed by a database
-2. Fetches data from the database and stores data in the database on every request, instead of periodically persisting the entire in-memory brain.
-
-The datastore is useful in cases where there's a need for greater reassurances of data integrity or in cases where multiple Hubot instances need to access the same database.

package/docs/index.md

@@ -1,125 +0,0 @@
----
-permalink: /docs/
----
-
-## Getting Started With Hubot
-
-You will need [node.js and npm](https://docs.npmjs.com/getting-started/installing-node). Once those are installed, we can install the hubot generator:
-
-    %  npm install -g yo generator-hubot
-
-This will give us the `hubot` [yeoman](http://yeoman.io/) generator. Now we
-can make a new directory, and generate a new instance of hubot in it. For example, if
-we wanted to make a bot called myhubot:
-
-
-    % mkdir myhubot
-    % cd myhubot
-    % yo hubot
-
-At this point, you'll be asked a few questions about who is creating the bot,
-and which [adapter](adapters.md) you'll be using. Adapters are hubot's
-way of integrating with different chat providers.
-
-If you are using git, the generated directory includes a .gitignore, so you can
-initialize and add everything:
-
-    % git init
-    % git add .
-    % git commit -m "Initial commit"
-
-If you'd prefer to automate your hubot build without being interactively
-prompted for its configuration, you can add the following options
-to the `yo hubot` command to do so:
-
-| Option                                      | Description                                            |
-|:--------------------------------------------|:-------------------------------------------------------|
-| `--owner="Bot Wrangler <bw@example.com>"`   | Bot owner, e.g. "Bot Wrangler <bw@example.com>"        |
-| `--name="Hubot"`                            | Bot name, e.g. "Hubot"                                 |
-| `--description="Delightfully aware robutt"` | Bot description, e.g. "Delightfully aware robutt"      |
-| `--adapter=campfire`                        | Bot adapter, e.g. "campfire"                           |
-| `--defaults`                                | Declare all defaults are set and no prompting required |
-
-You now have your own functional hubot! There's a `bin/hubot`
-command for convenience, to handle installing npm dependencies, loading scripts,
-and then launching your hubot.
-
-Note: Hubot can use Redis to persist data, so before you can start hubot on your own computer, if you want to persist data, then you should have Redis running on your machine accessible via `localhost`. Then, ensure that `hubot-redis-brain` is listed in `external-scripts.json` as an `Array` of module names (e.g. `['hubot-redis-brain']`) or an `object` where the key is the name of the module (e.g. `{'hubot-redis-brain': 'some arbitrary value'}`) where the value of the property in the object is passed to the module function as the second argument. The first argument being the hubot Robot instance.
-
-    % bin/hubot
-    Hubot>
-
-This starts hubot using the [shell adapter](./adapters/shell.md), which is mostly useful for development. Make note of the name in the `hubot>` prompt; this is the name your hubot will respond to with commands. If the prompt reads `myhubot>` then your commands must start with `myhubot <command>`.
-
-For example, to list available commands:
-
-    % bin/hubot
-    myhubot> myhubot help
-    myhubot> Shell: myhubot adapter - Reply with the adapter
-    myhubot animate me <query> - The same thing as `image me`, except adds a few parameters to try to return an animated GIF instead.
-    myhubot echo <text> - Reply back with <text>
-    myhubot help - Displays all of the help commands that Hubot knows about.
-    myhubot help <query> - Displays all help commands that match <query>.
-    myhubot image me <query> - The Original. Queries Google Images for <query> and returns a random top result.
-    myhubot map me <query> - Returns a map view of the area returned by `query`.
-    myhubot mustache me <url|query> - Adds a mustache to the specified URL or query result.
-    myhubot ping - Reply with pong
-    myhubot pug bomb N - get N pugs
-    myhubot pug me - Receive a pug
-    myhubot the rules - Make sure hubot still knows the rules.
-    myhubot time - Reply with current time
-    myhubot translate me <phrase> - Searches for a translation for the <phrase> and then prints that bad boy out.
-    myhubot translate me from <source> into <target> <phrase> - Translates <phrase> from <source> into <target>. Both <source> and <target> are optional
-    ship it - Display a motivation squirrel
-
-You almost definitely will want to change your hubot's name to add character. bin/hubot takes a `--name`:
-
-    % bin/hubot --name sam
-    sam>
-
-Your hubot will now respond as `sam`. This is
-case-insensitive, and can be prefixed with `@` or suffixed with `:`. These are equivalent:
-
-    SAM help
-    sam help
-    @sam help
-    sam: help
-
-## Scripts
-
-Hubot's power comes through scripts. There are hundreds of scripts written and maintained by the community. Find them by searching the [NPM registry](https://www.npmjs.com/browse/keyword/hubot-scripts) for `hubot-scripts <your-search-term>`. For example:
-
-```
-$ npm search hubot-scripts github
-NAME                  DESCRIPTION
-hubot-deployer        Giving Hubot the ability to deploy GitHub repos to PaaS providers hubot hubot-scripts hubot-gith
-hubot-gh-release-pr   A hubot script to create GitHub's PR for release
-hubot-github          Giving Hubot the ability to be a vital member of your github organization
-…
-```
-
-To use a script from an NPM package:
-
-1. Run `npm install --save <package-name>` to add the package as a dependency and install it.
-2. Add the package to `external-scripts.json`.
-3. Run `npm home <package-name>` to open a browser window for the homepage of the script, where you can find more information about configuring and installing the script.
-
-You can also put your own scripts under the `scripts/` directory. All scripts (files ending with either `.js` or `.mjs`) placed there are automatically loaded and ready to use with your hubot. Read more about customizing hubot by [writing your own scripts](scripting.md).
-
-## Adapters
-
-Hubot uses the adapter pattern to support multiple chat-backends. Here is a [list of available adapters](adapters.md), along with details on how to configure them.
-
-## Deploying
-
-You can deploy hubot to Heroku, which is the officially supported method. Additionally you are able to deploy hubot to a UNIX-like system or Windows. Please note the support for deploying to Windows isn't officially supported.
-
-* [Deploying Hubot onto Azure](./deploying/azure.md)
-* [Deploying Hubot onto Bluemix](./deploying/bluemix.md)
-* [Deploying Hubot onto Heroku](./deploying/heroku.md)
-* [Deploying Hubot onto Unix](./deploying/unix.md)
-* [Deploying Hubot onto Windows](./deploying/windows.md)
-
-## Patterns
-
-Using custom scripts, you can quickly customize Hubot to be the most life embettering robot he or she can be. Read [docs/patterns.md](patterns.md) for some nifty tricks that may come in handy as you teach your hubot new skills.