diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f956d37101..f461e95303 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -49,21 +49,45 @@ help prioritize the most common problems and requests. Fork the repo and make changes on your fork in a feature branch: -- If it's a bugfix branch, name it XXX-something where XXX is the number of the issue -- If it's a feature branch, create an enhancement issue to announce your intentions, and name it XXX-something where XXX is the number of the issue. +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. -Submit unit tests for your changes. Golang has a great testing suite built -in: use it! Take a look at existing tests for inspiration. Run the full test -suite against your change and the master. +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. -Submit any relevant updates or additions to documentation. +Make sure you include relevant updates or additions to documentation when +creating or modifying features. -Add clean code: +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `go fmt` before committing your changes. Most +editors have plugins that do this automatically, and there's also a git +pre-commit hook: -- Universally formatted code promotes ease of writing, reading, and maintenance. We suggest using gofmt before committing your changes. There's a git pre-commit hook made for doing so. -- curl -o .git/hooks/pre-commit https://raw.github.com/edsrzf/gofmt-git-hook/master/fmt-check && chmod +x .git/hooks/pre-commit +``` +curl -o .git/hooks/pre-commit https://raw.github.com/edsrzf/gofmt-git-hook/master/fmt-check && chmod +x .git/hooks/pre-commit +``` Pull requests descriptions should be as clear as possible and include a -referenced to all the issues that they address. +reference to all the issues that they address. -Add your name to the AUTHORS file. +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +Add your name to the AUTHORS file, but make sure the list is sorted and your +name and email address match your git configuration. The AUTHORS file is +regenerated occasionally from the git commit history, so a mismatch may result +in your changes being overwritten. diff --git a/docs/sources/contributing/contributing.rst b/docs/sources/contributing/contributing.rst index 689c4207ce..7b2b4da2d3 100644 --- a/docs/sources/contributing/contributing.rst +++ b/docs/sources/contributing/contributing.rst @@ -56,21 +56,46 @@ Conventions Fork the repo and make changes on your fork in a feature branch: -- If it's a bugfix branch, name it XXX-something where XXX is the number of the issue -- If it's a feature branch, create an enhancement issue to announce your intentions, and name it XXX-something where XXX is the number of the issue. +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. -Submit unit tests for your changes. Golang has a great testing suite built -in: use it! Take a look at existing tests for inspiration. Run the full test -suite against your change and the master. +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. -Submit any relevant updates or additions to documentation. +Make sure you include relevant updates or additions to documentation when +creating or modifying features. -Add clean code: +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run ``go fmt`` before committing your changes. Most +editors have plugins that do this automatically, and there's also a git +pre-commit hook: + +.. code-block:: bash + + curl -o .git/hooks/pre-commit https://raw.github.com/edsrzf/gofmt-git-hook/master/fmt-check && chmod +x .git/hooks/pre-commit -- Universally formatted code promotes ease of writing, reading, and maintenance. We suggest using gofmt before committing your changes. There's a git pre-commit hook made for doing so. -- curl -o .git/hooks/pre-commit https://raw.github.com/edsrzf/gofmt-git-hook/master/fmt-check && chmod +x .git/hooks/pre-commit Pull requests descriptions should be as clear as possible and include a -referenced to all the issues that they address. +reference to all the issues that they address. -Add your name to the AUTHORS file. +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using ``git rebase -i`` and ``git push -f``. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like ``Closes #XXX`` +or ``Fixes #XXX``, which will automatically close the issue when merged. + +Add your name to the AUTHORS file, but make sure the list is sorted and your +name and email address match your git configuration. The AUTHORS file is +regenerated occasionally from the git commit history, so a mismatch may result +in your changes being overwritten.