1========================= 2Contributing to testtools 3========================= 4 5Coding style 6------------ 7 8In general, follow `PEP 8`_ except where consistency with the standard 9library's unittest_ module would suggest otherwise. 10 11testtools currently supports Python 2.6 and later, including Python 3. 12 13Copyright assignment 14-------------------- 15 16Part of testtools raison d'etre is to provide Python with improvements to the 17testing code it ships. For that reason we require all contributions (that are 18non-trivial) to meet one of the following rules: 19 20* be inapplicable for inclusion in Python. 21* be able to be included in Python without further contact with the contributor. 22* be copyright assigned to Jonathan M. Lange. 23 24Please pick one of these and specify it when contributing code to testtools. 25 26 27Licensing 28--------- 29 30All code that is not copyright assigned to Jonathan M. Lange (see Copyright 31Assignment above) needs to be licensed under the `MIT license`_ that testtools 32uses, so that testtools can ship it. 33 34 35Testing 36------- 37 38Please write tests for every feature. This project ought to be a model 39example of well-tested Python code! 40 41Take particular care to make sure the *intent* of each test is clear. 42 43You can run tests with ``make check``. 44 45By default, testtools hides many levels of its own stack when running tests. 46This is for the convenience of users, who do not care about how, say, assert 47methods are implemented. However, when writing tests for testtools itself, it 48is often useful to see all levels of the stack. To do this, add 49``run_tests_with = FullStackRunTest`` to the top of a test's class definition. 50 51 52Discussion 53---------- 54 55When submitting a patch, it will help the review process a lot if there's a 56clear explanation of what the change does and why you think the change is a 57good idea. For crasher bugs, this is generally a no-brainer, but for UI bugs 58& API tweaks, the reason something is an improvement might not be obvious, so 59it's worth spelling out. 60 61If you are thinking of implementing a new feature, you might want to have that 62discussion on the [mailing list](testtools-dev@lists.launchpad.net) before the 63patch goes up for review. This is not at all mandatory, but getting feedback 64early can help avoid dead ends. 65 66 67Documentation 68------------- 69 70Documents are written using the Sphinx_ variant of reStructuredText_. All 71public methods, functions, classes and modules must have API documentation. 72When changing code, be sure to check the API documentation to see if it could 73be improved. Before submitting changes to trunk, look over them and see if 74the manuals ought to be updated. 75 76 77Source layout 78------------- 79 80The top-level directory contains the ``testtools/`` package directory, and 81miscellaneous files like ``README.rst`` and ``setup.py``. 82 83The ``testtools/`` directory is the Python package itself. It is separated 84into submodules for internal clarity, but all public APIs should be “promoted” 85into the top-level package by importing them in ``testtools/__init__.py``. 86Users of testtools should never import a submodule in order to use a stable 87API. Unstable APIs like ``testtools.matchers`` and 88``testtools.deferredruntest`` should be exported as submodules. 89 90Tests belong in ``testtools/tests/``. 91 92 93Committing to trunk 94------------------- 95 96Testtools is maintained using git, with its master repo at https://github.com 97/testing-cabal/testtools. This gives every contributor the ability to commit 98their work to their own branches. However permission must be granted to allow 99contributors to commit to the trunk branch. 100 101Commit access to trunk is obtained by joining the `testing-cabal`_, either as an 102Owner or a Committer. Commit access is contingent on obeying the testtools 103contribution policy, see `Copyright Assignment`_ above. 104 105 106Code Review 107----------- 108 109All code must be reviewed before landing on trunk. The process is to create a 110branch on Github, and make a pull request into trunk. It will then be reviewed 111before it can be merged to trunk. It will be reviewed by someone: 112 113* not the author 114* a committer 115 116As a special exception, since there are few testtools committers and thus 117reviews are prone to blocking, a pull request from a committer that has not been 118reviewed after 24 hours may be merged by that committer. When the team is larger 119this policy will be revisited. 120 121Code reviewers should look for the quality of what is being submitted, 122including conformance with this HACKING file. 123 124Changes which all users should be made aware of should be documented in NEWS. 125 126 127NEWS management 128--------------- 129 130The file NEWS is structured as a sorted list of releases. Each release can have 131a free form description and more or more sections with bullet point items. 132Sections in use today are 'Improvements' and 'Changes'. To ease merging between 133branches, the bullet points are kept alphabetically sorted. The release NEXT is 134permanently present at the top of the list. 135 136 137Release tasks 138------------- 139 140#. Choose a version number, say X.Y.Z 141#. In trunk, ensure __init__ has version ``(X, Y, Z, 'final', 0)`` 142#. Under NEXT in NEWS add a heading with the version number X.Y.Z. 143#. Possibly write a blurb into NEWS. 144#. Commit the changes. 145#. Tag the release, ``git tag -s testtools-X.Y.Z`` 146#. Run 'make release', this: 147 #. Creates a source distribution and uploads to PyPI 148 #. Ensures all Fix Committed bugs are in the release milestone 149 #. Makes a release on Launchpad and uploads the tarball 150 #. Marks all the Fix Committed bugs as Fix Released 151 #. Creates a new milestone 152#. Change __version__ in __init__.py to the probable next version. 153 e.g. to ``(X, Y, Z+1, 'dev', 0)``. 154#. Commit 'Opening X.Y.Z+1 for development.' 155#. If a new series has been created (e.g. 0.10.0), make the series on Launchpad. 156#. Push trunk to Github, ``git push --tags origin master`` 157 158.. _PEP 8: http://www.python.org/dev/peps/pep-0008/ 159.. _unittest: http://docs.python.org/library/unittest.html 160.. _MIT license: http://www.opensource.org/licenses/mit-license.php 161.. _Sphinx: http://sphinx.pocoo.org/ 162.. _restructuredtext: http://docutils.sourceforge.net/rst.html 163.. _testing-cabal: https://github.com/organizations/testing-cabal/ 164