Improve and genericize documentation, hooks, etc. (#2)

* docs for the day...

* more docs, more docs, more docs... throw more docs

* no credit humble-brag

* more documentation and formatting

* documentation formatting

LICENSE

@@ -1,3 +1,22 @@
+hubot-code-review: A Hubot script for GitHub code review on Slack
+
+Copyright 2017 Alley Interactive LLC
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+
+
                     GNU GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 

README.md

@@ -1,6 +1,115 @@
-# hubot-code-review
-hubot script for GitHub code review on Slack
+hubot-code-review
+===================
+
+[![Travis branch](https://img.shields.io/travis/alleyinteractive/hubot-code-review/master.svg?maxAge=2592000)](https://travis-ci.org/alleyinteractive/hubot-code-review)
+[![codecov](https://codecov.io/gh/alleyinteractive/hubot-code-review/branch/master/graph/badge.svg)](https://codecov.io/gh/alleyinteractive/hubot-code-review)
+[![npm (scoped)](https://img.shields.io/npm/v/hubot-code-review.svg?maxAge=2592000)](https://www.npmjs.com/package/hubot-code-review)
+
+A Hubot script for GitHub code review on Slack.
+
+## tldr;
+
+Drop a GitHub pull request url into a room, and Hubot adds the pull request
+to the room's queue (each room has its own queue)...
+
+![](/docs/images/submit-pr.png)
+
+Every 5 minutes, Hubot reports the current code review queue to the room (after an hour of
+no interaction, it messages @here with a warning and switches to hourly reminders)...
+
+![](/docs/images/remind-pr.png)
+
+A co-worker can claim it for review...
+
+![](/docs/images/claim-pr.png)
+
+Once the review is complete, a GitHub webhook listener catches approvals and Direct Messages the submitter:
+
+![](/docs/images/approve-pr.png)
+
+## Requirements
+
+You'll need [Hubot](http://hubot.github.com/) and
+[hubot-slack](https://github.com/slackapi/hubot-slack) > 4
+
+## Installation via NPM
+
+Run the following command to install this module as a Hubot dependency
+
+```
+npm install hubot-code-review --save
+```
+
+Confirm that hubot-code-review appears as a dependency in your Hubot package.json file.
+
+```
+"dependencies": {
+  ...
+  "hubot-code-review": "*",
+  ...
+}
+```
+
+To enable the script, add the hubot-code-review entry to the external-scripts.json file (you may need to create this file).
+
+```
+[
+  ...
+  "hubot-code-review",
+  ...
+]
+```
+
+## Configuration
+
+Code review queuing and notifications will work out of the box, but magic like
+file type lookups or DMs when your PR is approved/rejected require 2 things:
+
+1) **Create a `hubot-code-review` webhook in GitHub so that Hubot can notice any changes**
+
+- [GitHub webhook instructions for hubot-code-review](/docs/github-webhook.md)
+
+2) **Set Environmental variables:**
+
+- If ```HUBOT_GITHUB_TOKEN``` is set, Hubot can query the GitHub api for file type
+information on PR submission. Check out the instructions for configuring
+[`HUBOT_GITHUB_TOKEN` for hubot-code-review](/docs/HUBOT_GITHUB_TOKEN.md)
+
+- Set ```HUBOT_CODE_REVIEW_KARMA_DISABLED``` to `true` to prevent Hubot from listening for any
+[code review karma](/docs/code-review-karma.md) commands.
+
+- ```HUBOT_CODE_REVIEW_EMOJI_APPROVE``` an [Alley Interactive](https://www.alleyinteractive.com) cultural relic
+before the days GitHub incorporated [pull request reviews](https://help.github.com/articles/about-pull-request-reviews/).
+If this variable is `true`, a comment on the PR that includes one or more emoji conveys PR approval
+and will DM the submitter accordingly.
+
+
+## Usage
+
+`hubot help crs` - See a help document explaining how to use.
+
+	{GitHub pull request URL} [@user]   Add PR to queue and (optionally) notify @user or #channel
+	[hubot ]on it                       Claim the oldest _new_ PR in the queue
+	[hubot ]userName is on it           Tell hubot that userName has claimed the oldest _new_ PR in the queue
+	on *                                Claim all _new_ PRs
+	[userName is ]on cool-repo/123      Claim cool-repo/123 if no one else has claimed it
+	[userName is ]on cool               Claim a _new_ PR whose slug matches cool
+	(nm|ignore) cool-repo/123           Delete cool-repo/123 from queue regardless of status
+	(nm|ignore) cool                    Delete most recently added PR whose slug matches cool
+	hubot (nm|ignore)                   Delete most recently added PR from the queue regardless of status
+	hubot redo cool-repo/123            Allow another review _without_ decrementing previous reviewer's score
+	hubot (unclaim|reset) cool-repo/123 Reset CR status to new/unclaimed _and_ decrement reviewer's score
+	hubot list crs                      List all _unclaimed_ CRs in the queue
+	hubot list [status] crs             List CRs with matching optional status
+_Note that some commands require direct @hubot, some don't, and some work either way._
+
+
+*Code review statuses*
+
+	new			PR has just been added to the queue, no one is on it.
+	claimed		Someone is on this PR
+	approved	PR received a comment containing at least one emoji. Requires GitHub webhook.
+	merged		PR was merged and closed. Requires GitHub webhook.
+	closed		PR was closed without merging. Requires GitHub webhook.
 
-## Todo
 
-Document

docs/HUBOT_GITHUB_TOKEN.md

@@ -0,0 +1,28 @@
+`HUBOT_GITHUB_TOKEN` for hubot-code-review
+===================
+
+Adding a `HUBOT_GITHUB_TOKEN` environmental variable to hubot-code-review allows Hubot to
+query GitHub for file type information when reporting the PR back to the room.
+
+![](/docs/images/remind-pr.png)
+
+## Which GitHub account should create the 'Personal Access Token'?
+
+Some organizations might already have a dedicated user account for operational/deployment
+purposes. Whichever account you use to [create the access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) should have access to the repositories
+you want to enable the filetype checking for.
+
+## What scope does the HUBOT_GITHUB_TOKEN need?
+
+We'll need the `repo` scope.
+
+![](/docs/images/github-token.png)
+
+## Now what?
+
+After you've created your token, add it as an environmental variable to your Hubot instance.
+Hubot will now identify filetypes included in the PR, saving a curious click-through before
+claiming a PR :)
+
+If you haven't done so already, check out the
+[GitHub webhook instructions for hubot-code-review](/docs/github-webhook.md)

docs/code-review-karma.md

@@ -0,0 +1,20 @@
+Code Review Karma (aka. points/leaderboard)
+===================
+
+Code Reviews take time and effort to do right; `hubot-code-review` quietly
+keeps track of the number of `gives` and `takes` for code reviews across all rooms.
+
+## Configuration
+
+You can disable the code review ranking commands by setting the `HUBOT_CODE_REVIEW_KARMA_DISABLED`
+environmental variable to `true`
+
+## What can I say?
+
+	hubot: what are the code review rankings?
+	hubot: list all cr scores
+	hubot: what is my cr score?
+	hubot: what is [USER]'s cr score?
+	hubot: remove [USER]'s from cr rankings
+	hubot: remove [USER]'s from cr rankings
+	hubot: merge [USER1]'s cr score into [USER2]'

docs/github-webhook.md

@@ -0,0 +1,42 @@
+GitHub webhook instructions for hubot-code-review
+===================
+
+Adding a webhook from GitHub makes `hubot-code-review` even better. With the hook in place,
+Hubot can DM you when your PR has been approved or when someone has commented
+on your PR.
+
+## Organization or Repository Webhook?
+
+While you can add webhooks to individual repositories, adding an organization-wide hook is
+a convenient way to include all repositories (current and future) in your organization.
+
+![](/docs/images/organization-webhook.png)
+
+## Webhook specifics:
+
+*Payload Url:*
+Hubot will have a listener at `{BASEURL}/hubot/hubot-code-review` where `{BASEURL}` is your
+Hubot URL (on Heroku, this might be the `HEROKU_URL` environmental variable).
+
+*Content Type:*
+This should be set to `application/json`
+
+![](/docs/images/webhook-settings.png)
+
+*Which Events...:*
+
+We need to create a hook to the above url that passes along the following events:
+
+- Issue Comment
+- Pull Request
+- Pull Request Review
+
+![](/docs/images/webhook-events.png)
+
+
+## What now?
+
+You're set! This organization (or repository) will tell `hubot-code-review` whenever there
+are substantive changes to the PR status!
+
+If you haven't done so already, configure [`HUBOT_GITHUB_TOKEN` for hubot-code-review](/docs/HUBOT_GITHUB_TOKEN.md)

package.json

@@ -3,7 +3,7 @@
   "version": "0.1.1",
   "private": true,
   "author": "Alley Interactive <[email protected]>",
-  "description": "hubot script for GitHub code review on Slack",
+  "description": "A Hubot script for GitHub code review on Slack",
   "main": "index.coffee",
   "repository": {
     "type": "git",
@@ -23,20 +23,6 @@
     "lint": "node_modules/.bin/coffeelint src/",
     "lint-tests": "eslint -c .eslintrc --ext .js ./test"
   },
-  "contributors": [
-    {
-      "name": "Benjamin Bolton",
-      "url": "https://github.com/benpbolton"
-    },
-    {
-      "name": "Matthew Boynes",
-      "url": "https://github.com/mboynes"
-    },
-    {
-      "name": "Josh Kadis",
-      "url": "https://github.com/joshkadis"
-    }
-  ],
   "dependencies": {
     "githubot": "^1.0.0",
     "moment": "^2.8.3",

src/code-reviews.coffee

@@ -253,7 +253,7 @@ module.exports = (robot) ->
       msg.send code_reviews.queues_debug_room(msg.match[1])
 
   # Mark a CR as approved or closed when webhook received from GitHub
-  robot.router.post '/hubot/cr-comment', (req, res) ->
+  robot.router.post '/hubot/hubot-code-review', (req, res) ->
     # check header
     unless req.headers['x-github-event']
       res.statusCode = 400