CONTRIBUTING.md

Contributing

First, thank you for contributing!

We love pull requests from everyone. By participating in this project, you agree to abide by the thoughtbot code of conduct.

Here are a few technical guidelines to follow:

1. Open an issue to discuss a new feature.
2. Write tests.
3. Make sure the entire test suite passes locally and on CI.
4. Open a Pull Request.
5. Squash your commits after receiving feedback.
6. Party!

Configure Hound on Your Local Development Environment

1. After cloning the repository, run the setup script: ./bin/setup

2. Make sure that Postgres, and Redis, are both installed and running locally.

3. Log into your GitHub account and go to your developer application settings.

4. Under the Developer applications panel - Click on "Register new application" and fill in the details:

   • Application Name: Hound Development
   • Homepage URL: http://localhost:5000
   • Authorization Callback URL: http://localhost:5000

5. On the confirmation screen, copy the Client ID and Client Secret to GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in the .env.local file.

6. Run foreman start. Foreman will start the web server and the resque background job queue. NOTE: rails server will not load the appropriate environment variables and you'll get a "Missing secret_key_base for 'development' environment" error. Similarly, heroku local and forego start will fail to properly load .env.local.

7. Open localhost:5000 in a browser.

Setup Ngrok to Allow Webhooks

Ngrok allows Hound to receive webhooks from GitHub. If you'd like to develop or test a feature involving GitHub sending a pull request notification to your local Hound server you'll need to have ngrok or something similar set up.

To get started with ngrok, sign up for an ngrok account and configure ngrok locally by installing ngrok and running:

ngrok authtoken <your-token>

1. Launch ngrok on port 5000 (we recommend running ngrok with a custom subdomain for easy and persistent configuration, but this requires a paid ngrok account. You can still run Hound with a free ngrok account, but it will require keeping the GitHub developer application configuration and your .env.local files up to date if your ngrok subdomain changes).

   • If you're using a custom subdomain: ngrok http -subdomain=<your-initials>-hound 5000

   • If you're using a free ngrok plan: ngrok http 5000

2. Set the HOST variable in your .env.local to your ngrok host, e.g. <your-subdomain>.ngrok.io.

3. Change ENABLE_HTTPS to 'yes' in the .env.local file.

4. Log into your GitHub account and go to your developer application settings.

5. Under the Developer applications panel - Click on "Register new application" and fill in the details:

   • Application Name: Hound Development
   • Homepage URL: https://<your-subdomain>.ngrok.io
   • Authorization Callback URL: https://<your-subdomain>.ngrok.io

6. On the confirmation screen, copy the Client ID and Client Secret to GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in the .env.local file.

7. On the personal access token page, click "Generate new token" and fill in token details:

   • Token description: Hound Development
   • Select scopes: repo and user:email

8. On the confirmation screen, copy the generated token to HOUND_GITHUB_TOKEN in the .env.local file. Also update HOUND_GITHUB_USERNAME to be your username.

9. Run foreman start. Foreman will start the web server and the resque background job queue. NOTE: rails server will not load the appropriate environment variables and you'll get a "Missing secret_key_base for 'development' environment" error. Similarly, heroku local and forego start will fail to properly load .env.local.

10. Open https://<your-subdomain>.ngrok.io in a browser.

Testing

1. Set up your development environment as per above.
2. Run rake to execute the full test suite.

To test Stripe payments on staging use this fake credit card number.

Card	Number	Expiration	CVV
Visa	4242424242424242	Any future date	Any 3 digits

Linters

The main Hound app (this app) receives PR hooks from GitHub, then it communicates with the Linters app (or a few individual linter services) to review changed files in the PR. Linters communcate back with vioaltions they found, and the Hound app sends comments back to GitHub.

Here is the list of all the linters and where to find them, as well as any default configuration they might use:

1. Ruby
   • RuboCop
     • RuboCop
     • houndci/linters
   • Flog
     • Flog
     • houndci/linters
   • Reek
     • Reek
     • houndci/linters
2. CoffeeScript
   • CoffeeLint
   • houndci/linters
3. JavaScript
   • JSHint
     • JSHint
     • houndci/linters
   • ESLint
     • ESLint
     • houndci/linters
     • default config
4. TypeScript
   • TSLint
   • houndci/linters
5. SCSS
   • SCSS-Lint
   • houndci/linters
   • default config
6. Haml
   • HAML-Lint
   • houndci/linters
   • default config
7. Elixir
   • Credo
   • houndci/linters
8. Go
   • Golint
   • houndci/go
9. Markdown
   • Remark
   • houndci/remark
10. Swift
    • SwiftLint
    • houndci/swift
    • default config

Writing a Linter

Linters check code snippets for style violations. They operate by polling a Resque queue.

Linter jobs are created with the following arguments:

• commit_sha - The git commit SHA of the code snippet. This should be passed through to the outbound queue.
• config - The configuration for the linter. This will be linter specific.
• content - The source code to check for violations.
• filename - The name of the source file for the code snippet. This should be passed through to the outbound queue.
• linter_name - A string that identifies which linter is assigned to this linter job. This must be passed through to the outbound queue unmodified.
• patch - The patch content from GitHub for the file being reviewed. This should be passed through to the outbound queue.
• pull_request_number - The GitHub pull request number. This should be passed through to the outbound queue.

Once linting is complete, resulting violations should be posted to the outbound "CompletedFileReviewJob" queue:

• violations - An array of violation objects. Each violation requires the following:
  • line - The line number where the violation occurred.
  • message - A message describing the violation. This will be the contents of the Pull Request comment.
• filename - The name of the source file for the code snippet. This is provided by the inbound queue.
• commit_sha - The git commit SHA of the code snippet. This is provided by the inbound queue.
• linter_name - A string that identifies which linter is assigned to this linter job. This is provided by the inbound queue.
• patch - The patch content from GitHub for the file being reviewed. This is provided by the inbound queue.

If the given config is invalid, the invalid file should be posted to the outbound ReportInvalidConfigJob queue:

• commit_sha - The git commit SHA of the code snippet. This is provided by the inbound queue.
• linter_name - The name of the linter that received an invalid config file.
• pull_request_number - The GitHub pull request number. This is provided by the inbound queue.

Deploying

If you have previously run the bin/setup script, you can deploy to staging and production with:

% bin/deploy staging
% bin/deploy production

Contributor License Agreement

If you submit a Contribution to this application's source code, you hereby grant to thoughtbot, inc. a worldwide, royalty-free, exclusive, perpetual and irrevocable license, with the right to grant or transfer an unlimited number of non-exclusive licenses or sublicenses to third parties, under the Copyright covering the Contribution to use the Contribution by all means, including but not limited to:

• to publish the Contribution,
• to modify the Contribution, to prepare Derivative Works based upon or containing the Contribution and to combine the Contribution with other software code,
• to reproduce the Contribution in original or modified form,
• to distribute, to make the Contribution available to the public, display and publicly perform the Contribution in original or modified form.