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``.