sync latest docs

docs/best-practices.md

@@ -1,4 +1,4 @@
-# Best Practices
+# Best practices for Probot plugins
 
 First and foremost, your plugin must obey the [The Three Laws of Robotics](https://en.wikipedia.org/wiki/Three_Laws_of_Robotics):
 
@@ -57,6 +57,4 @@ Plugins _should_ allow all settings to customized for each installation.
 
 ### Store configuration in the repository
 
-Any configuration _should_ be stored in the repository. Unless the plugin is using files from an established convention, the configuration _should_ be stored in the `.github` directory.
-
-For example, the [owners](https://github.com/probot/owners) plugin reads from the `OWNERS` file, which is a convention that existed before the plugin was created, while the [configurer](https://github.com/probot/configurer) plugin reads from `.github/config.yml`.
+Any configuration _should_ be stored in the repository. Unless the plugin is using files from an established convention, the configuration _should_ be stored in the `.github` directory. See the [API docs for `context.config`](https://probot.github.io/probot/latest/Context.html#config).

docs/deployment.md

@@ -72,7 +72,11 @@ Probot runs like [any other Node app](https://devcenter.heroku.com/articles/depl
         -----> Launching... done
               http://arcane-lowlands-8408.herokuapp.com deployed to Heroku
 
-Your plugin should be up and running!
+1. Your plugin should be up and running! To verify that your plugin 
+   is receiving webhook data, you can tail your app's logs:
+
+      $ heroku config:set LOG_LEVEL=trace
+      $ heroku logs --tail
 
 ### Now
 

docs/development.md

@@ -16,6 +16,8 @@ You'll need to create a test repository and install your app by clicking the "In
 
 Whenever you come back to work on the app after you've already had it running once, you should only need to run `$ npm start`.
 
+Optionally, you can also run your plugin through [nodemon](https://github.com/remy/nodemon#nodemon) which will listen on any files changes in your local development environment and automatically restart the server. After installing nodemon, you can run `nodemon --exec "npm start"` and from there the server will automatically restart upon file changes.
+
 ## Debugging
 
 1. Always run `$ npm install` and restart the server if package.json has changed.

docs/plugins.md

@@ -1,7 +1,3 @@
----
----
-
-
 # Plugins
 
 A plugin is just a [Node.js module](https://nodejs.org/api/modules.html) that exports a function:
@@ -94,15 +90,57 @@ $ probot run -a APP_ID -P private-key.pem ./index.js
 Listening on http://localhost:3000
 ```
 
-## Publishing your bot
+## HTTP Routes
 
-Plugins can be published in NPM modules, which can either be deployed as stand-alone bots, or combined with other plugins.
+Calling `robot.route('/my-plugin')` will return an [express](http://expressjs.com/) router that you can use to expose HTTP endpoints from your plugin.
 
-Use the [plugin-template](https://github.com/probot/plugin-template) repository to get started building your plugin as a node module.
+```js
+module.exports = robot => {
+  // Get an express router to expose new HTTP endpoints
+  const app = robot.route('/my-plugin');
+
+  // Use any middleware
+  app.use(require('express').static(__dirname + '/public'));
+
+  // Add a new route
+  app.get('/hello-world', (req, res) => {
+    res.end('Hello World');
+  });
+};
+```
+
+Visit https://localhost:3000/my-plugin/hello-world to access the endpoint.
+
+It is strongly encouraged to use the name of your package as the prefix so none of your routes or middleware conflict with other plugins. For example, if [`probot/owners`](https://github.com/probot/owners) exposed an endpoint, the plugin would call `robot.route('/owners')` to prefix all endpoints with `/owners`.
+
+See the [express documentation](http://expressjs.com/en/guide/routing.html) for more information.
+
+## Simulating webhooks
+
+As you are developing your plugin, you will likely want to test it by repeatedly trigging the same webhook. You can simulate a webhook being delivered by saving the payload to a file, and then calling `probot simulate` from the command line.
+
+To save a copy of the payload, go to the  [settings](https://github.com/settings/apps) page for your App, and go to the **Advanced** tab. Click on one of the **Recent Deliveries** to expand it and see the details of the webhook event. Copy the JSON from the the **Payload** and save it to a new file. (`test/fixtures/issues.labeled.json` in this example).
+
+![](https://user-images.githubusercontent.com/173/28491924-e03e91f2-6ebe-11e7-9570-6d48da68c6ca.png)
+
+Next, simulate this event being delivered by running:
 
 ```
-$ curl -L https://github.com/probot/plugin-template/archive/master.tar.gz | tar xvz
-$ mv plugin-template-master probot-myplugin && cd probot-myplugin
+$ node_modules/.bin/probot simulate issues test/fixtures/issues.labeled.json ./index.js
+```
+
+## Publishing your bot
+
+Plugins can be published in npm modules, which can either be deployed as stand-alone bots, or combined with other plugins.
+
+Use [create-probot-plugin](https://github.com/probot/create-probot-plugin) to get started building your plugin as a node module.
+
+```
+$ npm install -g create-probot-app
+
+$ create-probot-plugin my-plugin
+$ cd my-plugin
+$ npm install
 ```
 
 ## Next