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