Merge pull request #36 from stephenyeargin/readme-updates-contributing

Add CONTRIBUTING.md, update README on config vars

Author: stephenyeargin

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing to hubot-grafana
+
+We are proud to have [several contributors](https://github.com/stephenyeargin/hubot-grafana/graphs/contributors) to this Hubot Script Package and want you to be one! Here are some general suggestions to help make sure your PR is merged quickly.
+
+This follows the standard [GitHub Flow](https://guides.github.com/introduction/flow/), with some notes about working with NPM modules.
+
+1. [Open a GitHub Issue](https://github.com/stephenyeargin/hubot-grafana/issues/new) before starting. This is a great way to get feedback from other users on your idea and helps clarify what the upcoming PR will accomplish.
+2. [Fork the repository](https://github.com/stephenyeargin/hubot-grafana/fork) to your account or organization.
+3. Clone the repository locally and run `npm install` to download the necessary dependancies.
+4. Run the test suite with `npm test` in your cloned repository. This is to make sure you've got everything you need to get started.
+5. Use `npm link` in the cloned repository and then run `nmp link hubot-grafana` in your Hubot checkout to connect your cloned version to your local Hubot install. Now you can test changes with your own data!
+6. Commit and push changes back to your forked repository.
+7. [Open a Pull Request](https://github.com/stephenyeargin/hubot-grafana/compare) with your repository against the parent one to submit your changes.
+8. See if the the CI tests that run automatically upon opening a Pull Request pass. If not, double check your work locally with `npm test` again to resolve any issues.
+
+Note: You won't need to do a version bump in the `package.json` file as we have a [Grunt](http://gruntjs.com) task for handling that.
+
+## Tips
+
+- Test coverage makes the world go round. If you add a feature or fix a bug, be sure to adjust the tests to account for it when practical.
+- Configuration options are preferable to changing something globally. Many folks may depend on the current behavior (e.g. the default time window) and want to leave the default in place.
+- This package is designed to work with all Hubot adapters, so we are not wanting to limit it to only folks who use Slack, HipChat, etc. See [`robot.adapterName`](https://github.com/github/hubot/pull/663) if you want to create an adapter-specific feature.
+- If you find yourself copying large blocks of code, consider refactoring it to be a bit more [DRY](https://en.wikipedia.org/wiki/Don't_repeat_yourself).
+- `robot.logger.debug` and `robot.logger.error` are helpful methods. You can set your `HUBOT_LOG_LEVEL` locally to see the output of these methods as your code is run.
+- If you have something super custom (say, wanting to prefix every command with "hey Siri ..."), it is totally fine to fork this repository and _not_ submit back a Pull Request. You can include your forked version in Hubot by specifying the repository URL in the version field in `package.json`.
+
+## Thank You!
+
+You are super awesome for taking the time to contribute to Open Source Software like this project. :heart:

README.md

@@ -24,17 +24,30 @@ Then add **hubot-grafana** to your `external-scripts.json`:
 
 ## Configuration Variables
 
-- `HUBOT_GRAFANA_HOST` - Host for your Grafana 2.x install, e.g. 'http://play.grafana.org'
-- `HUBOT_GRAFANA_API_KEY` - API key for a particular user
-- `HUBOT_GRAFANA_QUERY_TIME_RANGE` - Optional; Default time range for queries (defaults to 6h)
-- `HUBOT_GRAFANA_S3_ENDPOINT` - Optional; Endpoint of the S3 API (useful for S3 compatible API, defaults to s3.amazonaws.com)
-- `HUBOT_GRAFANA_S3_BUCKET` - Optional; Name of the S3 bucket to copy the graph into
-- `HUBOT_GRAFANA_S3_ACCESS_KEY_ID` - Optional; Access key ID for S3
-- `HUBOT_GRAFANA_S3_SECRET_ACCESS_KEY` - Optional; Secret access key for S3
-- `HUBOT_GRAFANA_S3_PREFIX` - Optional; Bucket prefix (useful for shared buckets)
-- `HUBOT_GRAFANA_S3_REGION` - Optional; Bucket region (defaults to us-standard)
+### General Settings
 
-Example:
+| Configuration Variable           | Required | Description                    |
+| -------------------------------- | -------- | ------------------------------ |
+| `HUBOT_GRAFANA_HOST`             | **Yes**  | Host for your Grafana 2.x install, e.g. `http://play.grafana.org` |
+| `HUBOT_GRAFANA_API_KEY`          | _Yes^_   | API key for a particular user |
+| `HUBOT_GRAFANA_QUERY_TIME_RANGE` | No       | Default time range for queries (defaults to 6h) |
+
+^ _Not required for `auth.anonymous` Grafana configurations. All other authentication models will require a user-specific API key._
+
+### Amazon S3 Image Hosting
+
+Recommended if you use a service such as Slack or HipChat. You can omit all of these settings if you do not plan to use S3.
+
+| Configuration Variable               | Required | Description                |
+| ------------------------------------ | -------- | -------------------------- |
+| `HUBOT_GRAFANA_S3_BUCKET`            | **Yes**  | Name of the S3 bucket to copy the graph into |
+| `HUBOT_GRAFANA_S3_ACCESS_KEY_ID`     | **Yes**  | Access key ID for S3 |
+| `HUBOT_GRAFANA_S3_SECRET_ACCESS_KEY` | **Yes**  | Secret access key for S3 |
+| `HUBOT_GRAFANA_S3_PREFIX`            | No       | Bucket prefix (useful for shared buckets) |
+| `HUBOT_GRAFANA_S3_REGION`            | No       | Bucket region (defaults to us-standard) |
+| `HUBOT_GRAFANA_S3_ENDPOINT`          | No       | Endpoint of the S3 API (useful for S3 compatible API, defaults to s3.amazonaws.com) |
+
+### Example Configuration
 
 ```
 export HUBOT_GRAFANA_HOST=http://play.grafana.org
@@ -44,7 +57,6 @@ export HUBOT_GRAFANA_S3_BUCKET=mybucket
 export HUBOT_GRAFANA_S3_ACCESS_KEY_ID=ABCDEF123456XYZ
 export HUBOT_GRAFANA_S3_SECRET_ACCESS_KEY=aBcD01234dEaDbEef01234
 export HUBOT_GRAFANA_S3_PREFIX=graphs
-export HUBOT_GRAFANA_S3_REGION=us-standard
 ```
 
 ## Sample Interaction