From cbfb229bf3661c501d402f68ab6dc6f58b1595dc Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Sun, 13 Nov 2016 09:58:00 +0100 Subject: [PATCH] Improve contributing guide --- CONTRIBUTING.rst | 105 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 88 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index d1cc9a5a..7086b12a 100644 --- a/CONTRIBUTING.rst +++ b/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_. - 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. - You won't get any feedback until it's green unless you ask for it. -- If your change is noteworthy, add an entry to the changelog_. - 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`_. + +Workflow +-------- + +- No contribution is too small! + Please submit as many fixes for typos and grammar bloopers as you can! +- Try to limit each pull request to *one* change only. - *Always* add tests and docs for your code. - This is a hard rule; patches with missing tests or documentation won’t be merged. -- Write `good test docstrings`_. -- Obey `PEP 8`_ and `PEP 257`_. -- If you address review feedback, make sure to bump the pull request. + This is a hard rule; patches with missing tests or documentation can't be accepted. +- Make sure your changes pass our CI_. + You won't get any feedback until it's green unless you ask for it. +- 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 `_] + - Fix nasty bug. + The bug really *was* nasty. + [`#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/