1 Contributing 2 ============ 3 4 Pull requests are more than welcome both to the library and to the 5 documentation. Some useful information: 6 7 - We aim to follow PEP 8 in the library, but ignoring the 8 79-character-per-line limit, instead following a soft limit of 99, 9 but allowing lines over this where it is the readable thing to do. 10 11 - We aim to follow PEP 257 for all docstrings, and make them properly 12 parseable by Sphinx while generating API documentation. 13 14 - We keep ``pyflakes`` reporting no errors or warnings at all times. 15 16 - We keep the master branch passing all tests at all times on all 17 supported versions. 18 19 `Travis CI <https://travis-ci.org/html5lib/html5lib-python/>`_ is run 20 against all pull requests and should enforce all of the above. 21 22 We use `Opera Critic <https://critic.hoppipolla.co.uk/>`_ as an external 23 code-review tool, which uses your GitHub login to authenticate. You'll 24 get email notifications for issues raised in the review. 25 26 27 Patch submission guidelines 28 --------------------------- 29 30 - **Create a new Git branch specific to your change.** Do not put 31 multiple fixes/features in the same pull request. If you find an 32 unrelated bug, create a distinct branch and submit a separate pull 33 request for the bugfix. This makes life much easier for maintainers 34 and will speed up merging your patches. 35 36 - **Write a test** whenever possible. Following existing tests is often 37 easiest, and a good way to tell whether the feature you're modifying 38 is easily testable. 39 40 - **Make sure documentation is updated.** Keep docstrings current, and 41 if necessary, update the Sphinx documentation in ``doc/``. 42 43 - **Add a changelog entry** at the top of ``CHANGES.rst`` following 44 existing entries' styles. 45 46 - **Run tests with tox** if possible, to make sure your changes are 47 compatible with all supported Python versions. 48 49 - **Squash commits** before submitting the pull request so that a single 50 commit contains the entire change, and only that change (see the first 51 bullet). 52 53 - **Don't rebase after creating the pull request.** Merge with upstream, 54 if necessary, and use ``git commit --fixup`` for fixing issues raised 55 in a Critic review or by a failing Travis build. The reviewer will 56 squash and rebase your pull request while accepting it. Even though 57 GitHub won't recognize the pull request as accepted, the squashed 58 commits will properly specify you as the author. 59 60 - **Attribute yourself** in ``AUTHORS.rst``. 61
