README.md in hubstats-0.4.4 vs README.md in hubstats-0.5.0
- old
+ new
@@ -1,65 +1,107 @@
# Hubstats [](https://travis-ci.org/sportngin/hubstats)
Hubstats is a rails plugin which allows you to search and monitor pull requests made across a collection of repositories. It also gives extra statistics about users and pull requests not found on GitHub.
## Setup
+The following setup is designed to only be used when integrating this plugin into a rails application.
-The following setup is designed to only be used when integrating this plugin into a rails application or for when adding new migrations.
-
Run `rails generate hubstats:install`.
+
+ Configure `octokit.yml` with your GitHub information (see below).
Run `rake hubstats:install:migrations`.
- Run `rake hubstats:setup` to run the necessary migrations and start pulling data from Github.
+ Run `rake hubstats:setup` to run the necessary migrations and start pulling data from GitHub.
Add 'mount Hubstats::Engine => "/hubstats"' to your apps routes file.
## Configuration
-
### Authentication
+Hubstats needs GitHub credentials to access your repositories, these can be setup in one of two ways:
-Hubstats needs Github credentials to access your repos, these can be setup in one of two ways:
+#### GitHub API Tokens
+Add your GitHub API token (called `access_token`) or ClientID and Secret to `octokit.yml`.
-#### Configuring the `octokit.yml`
+#### Environment Variables
+Hubstats can also use OAUTH access tokens stored in ENV["GITHUB_API_TOKEN"] or for Application Authentication in ENV["CLIENT_ID"] and ENV["CLIENT_SECRET"], if for some reason you don't want to store them in `octokit.yml`.
-Add your GitHub API token or ClientID and Secret to `octokit.yml`.
+### Configuring Data to be Received from GitHub
+#### Organizations to Follow
+Hubstats tracks certain repositories and teams that are part of an organization. Therefore, you must whitelist the specific GitHub organization to track in `octokit.yml`. The list of organizations should look something like this:
-#### Environment Variables
+```
+org_list:
+ - sportngin
+ ```
+
+#### Repositories to Follow
+If you only want Hubstats to watch certain repositories, you can set it to watch a list of specific repositories in `octokit.yml`. Otherwise, the default will be for Hubstats to watch an entire organization's list of repositories. The list of repositories should look like either:
-Hubstats can also use OAUTH access tokens stored in ENV["GITHUB_API_TOKEN"] or for Application Authentication in ENV["CLIENT_ID"] and ENV["CLIENT_SECRET"], if for some reason you don't want to store them in `octokit.yml`.
+```
+repo_list:
+ - sportngin/repo_one
+ - sportngin/repo_two
+ - sportngin/repo_three
+```
-### Webhooks
+#### Teams to Follow
+If you want Hubstats to watch certain teams to give back GitHub team metrics, then you must whitelist a list of teams in the `octokit.yml`. If no list of teams is added, then there will be no team metrics. The list of teams should look something like:
-Hubstats uses GitHub webhooks to keep itself updated. It requires you to set a secret as well as an endpoint to push to.
+```
+team_list:
+ - Team One
+ - Team Two
+ - Team Three
+```
-To generate a secret run:
+Also, the GitHub API token in `octokit.yml` must be a member of all of the teams listed in order to receive webhooks and populate team data.
+#### Users to Ignore
+If there are specific users that should not show up on any lists or in any metrics, then they can be placed on the `ignore_users_list` part of the `octokit.yml`. This list is referenced when making the list of users in teams. The list of users to ignore should look like:
+
+```
+ignore_users_list:
+ - user_login_one
+ - user_login_two
+ - user_login_three
+```
+
+### Webhooks
+Hubstats uses GitHub webhooks to keep its data updated. It requires you to set a secret as well as an endpoint to push to.
+
+To generate a secret run:
```
ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'
```
-
Set the endpoint to be:
www.yourdomain.com/hubstats/handler
-### Repositories
-
-Hubstats needs to know what repos for it to watch. You can set it to watch either an entire organization or a list of specific repos in octokit.yml.
-
## Testing
+All of the automated tests are written in RSpec. To run these tests, run the following commands, assuming that there are two already existent local databases titled `hubstats_development` and `hubstats_test`:
+```
+cd test/dummy/
+rake db:test:prepare
+bundle exec rspec
+```
+To test what Hubstats would actually look like on a web browser, we need to install the plugin into a Rails application to run. This is because Hubstats is a plugin, not an application. The `test` directory is also a dummy rails application for manually testing the UI by serving Hubstats locally. When developing and using the `test/dummy` locally, then the test will automatically sync with any updated code, so it doesn't need to be re-served when changes are made with the normal Rails application. When in the development process, one just needs to run:
+```
+cd test/dummy/
+bundle exec rails s
+```
+to serve the plugin. http://guides.rubyonrails.org/plugins.html will give more information on the implementation of a Rails plugin.
-All of the automated tests are written in RSpec. Since hubstats is a plugin, not an application, we need to install the plugin into a Rails application to run. The `test` directory is a dummy rails application for manually testing the UI by serving hubstats locally. When developing and using the `test/dummy` locally, then the test will automatically sync with any updated code, so it doesn't need to be re-served when changes are made with the normal Rails application. When in the development process, one just needs to run `bundle exec rails s` once from the command line (while in `test/dummy`) to serve the plugin. http://guides.rubyonrails.org/plugins.html will give more information on the implementation of a Rails plugin.
-
## TL:DR
-
Run `rails generate hubstats:install`.
- Configure `octokit.yml` with your Github information.
+ Configure `octokit.yml` with your GitHub information (see above).
Run `rake hubstats:install:migrations`.
Run `rake hubstats:setup`.
Add 'mount Hubstats::Engine => "/hubstats"' to your routes file.
+
+<hr>
This project rocks and uses MIT-LICENSE.