blob: 8c5e198535d2406200812485eb207a9a3e28e305 [file] [log] [blame]
Contributing
============
Pull requests are more than welcome both to the library and to the
documentation. Some useful information:
- We aim to follow PEP 8 in the library, but ignoring the
79-character-per-line limit, instead following a soft limit of 99,
but allowing lines over this where it is the readable thing to do.
- We aim to follow PEP 257 for all docstrings, and make them properly
parseable by Sphinx while generating API documentation.
- We keep ``pyflakes`` reporting no errors or warnings at all times.
- We keep the master branch passing all tests at all times on all
supported versions.
`Travis CI <https://travis-ci.org/html5lib/html5lib-python/>`_ is run
against all pull requests and should enforce all of the above.
We use `Opera Critic <https://critic.hoppipolla.co.uk/>`_ as an external
code-review tool, which uses your GitHub login to authenticate. You'll
get email notifications for issues raised in the review.
Patch submission guidelines
---------------------------
- **Create a new Git branch specific to your change.** Do not put
multiple fixes/features in the same pull request. If you find an
unrelated bug, create a distinct branch and submit a separate pull
request for the bugfix. This makes life much easier for maintainers
and will speed up merging your patches.
- **Write a test** whenever possible. Following existing tests is often
easiest, and a good way to tell whether the feature you're modifying
is easily testable.
- **Make sure documentation is updated.** Keep docstrings current, and
if necessary, update the Sphinx documentation in ``doc/``.
- **Add a changelog entry** at the top of ``CHANGES.rst`` following
existing entries' styles.
- **Run tests with tox** if possible, to make sure your changes are
compatible with all supported Python versions.
- **Squash commits** before submitting the pull request so that a single
commit contains the entire change, and only that change (see the first
bullet).
- **Don't rebase after creating the pull request.** Merge with upstream,
if necessary, and use ``git commit --fixup`` for fixing issues raised
in a Critic review or by a failing Travis build. The reviewer will
squash and rebase your pull request while accepting it. Even though
GitHub won't recognize the pull request as accepted, the squashed
commits will properly specify you as the author.
- **Attribute yourself** in ``AUTHORS.rst``.