Improve contributing guide

CONTRIBUTING.rst

@@ -1,26 +1,93 @@
 How To Contribute
 =================
 
-Every open source project lives due to generous help by contributors sacrificing their time; ``attrs`` is no different.
+First off, thank you for considering contributing to ``attrs``!
+It's people like *you* who make it is such a great tool for everyone.
 
-Here are a few guidelines to get you started:
+Here are a few guidelines to get you started (but don't be afraid to open half-finished PRs and ask questions if something is unclear!):
 
-- Try to limit each pull request to one change only.
+
-- To run the test suite, all you need is a recent tox_.
+Workflow
-  It will ensure the test suite runs with all dependencies against all Python versions just as it will on `Travis CI`_.
+--------
-  If you lack some Python versions, you can can always limit the environments like ``tox -e py27,py35`` (in that case you may want to look into pyenv_, which makes it very easy to install many different Python versions in parallel).
+
-- Make sure your changes pass our CI.
+- No contribution is too small!
-  You won't get any feedback until it's green unless you ask for it.
+  Please submit as many fixes for typos and grammar bloopers as you can!
-- If your change is noteworthy, add an entry to the changelog_.
+- Try to limit each pull request to *one* change only.
-  Use present tense, semantic newlines, and add a link to your pull request.
-- No contribution is too small; please submit as many fixes for typos and grammar bloopers as you can!
-- Don’t break `backward compatibility`_.
 - *Always* add tests and docs for your code.
-  This is a hard rule; patches with missing tests or documentation won’t be merged.
+  This is a hard rule; patches with missing tests or documentation can't be accepted.
-- Write `good test docstrings`_.
+- Make sure your changes pass our CI_.
-- Obey `PEP 8`_ and `PEP 257`_.
+  You won't get any feedback until it's green unless you ask for it.
-- If you address review feedback, make sure to bump the pull request.
+- Once you've addressed review feedback, make sure to bump the pull request with a short note.
   Maintainers don’t receive notifications when you push new commits.
+- Don’t break `backward compatibility`_.
+
+
+Code
+----
+
+- Obey `PEP 8`_ and `PEP 257`_.
+  We use the ``"""``\ -on-separate-lines style for docstrings:
+
+  .. code-block:: python
+
+     def func(x):
+         """
+         Does something.
+
+         :param str x: A very important parameter.
+
+         :rtype: str
+         """
+- If you add or change public APIs, tag the docstring using ``..  versionadded:: 16.0.0 WHAT`` or ``..  versionchanged:: 16.2.0 WHAT``.
+- Prefer double quotes (``"``) over single quotes (``'``) unless the string contains double quotes itself.
+
+
+Tests
+-----
+
+- Write your asserts as ``expected == actual`` to line them up nicely:
+
+  .. code-block:: python
+
+     x = f()
+
+     assert 42 == x.some_attribute
+     assert "foo" == x._a_private_attribute
+
+- To run the test suite, all you need is a recent tox_.
+  It will ensure the test suite runs with all dependencies against all Python versions just as it will on Travis CI.
+  If you lack some Python versions, you can can always limit the environments like ``tox -e py27,py35`` (in that case you may want to look into pyenv_, which makes it very easy to install many different Python versions in parallel).
+- Write `good test docstrings`_.
+- To ensure new features work well with the rest of the system, they should be also added to our `Hypothesis`_ testing strategy which you find in ``tests/util.py``.
+
+
+Documentation
+-------------
+
+- Use `semantic newlines`_ in reStructuredText_ files (files ending in ``.rst``):
+
+  .. code-block:: rst
+
+     This is a sentence.
+     This is another sentence.
+
+- If you add a new feature, demonstrate its awesomeness in the `examples page`_!
+- If your change is noteworthy, add an entry to the changelog_.
+  Use present tense, `semantic newlines`_, and add a link to your pull request:
+
+  .. code-block:: rst
+
+     - Add awesome new feature.
+       The feature really *is* awesome.
+       [`#1 <https://github.com/hynek/attrs/pull/1>`_]
+     - Fix nasty bug.
+       The bug really *was* nasty.
+       [`#2 <https://github.com/hynek/attrs/pull/2>`_]
+
+****
+
+Again, this list is mainly to help you to get started by codifying tribal knowledge and expectations.
+If something is unclear, feel free to ask for help!
 
 Please note that this project is released with a Contributor `Code of Conduct`_.
 By participating in this project you agree to abide by its terms.
@@ -37,5 +104,9 @@ Thank you for considering contributing to ``attrs``!
 .. _changelog: https://github.com/hynek/attrs/blob/master/CHANGELOG.rst
 .. _`backward compatibility`: https://attrs.readthedocs.io/en/latest/backward-compatibility.html
 .. _`tox`: https://testrun.org/tox/
-.. _`Travis CI`: https://travis-ci.org/
 .. _pyenv: https://github.com/yyuu/pyenv
+.. _reStructuredText: http://sphinx-doc.org/rest.html
+.. _semantic newlines: http://rhodesmill.org/brandon/2012/one-sentence-per-line/
+.. _examples page: https://github.com/hynek/attrs/blob/master/docs/examples.rst
+.. _Hypothesis: https://hypothesis.readthedocs.org
+.. _CI: https://travis-ci.org/hynek/attrs/