Merge pull request #288 from titanous/expand-contributing

Expand the contributing guidelines

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.

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.