lib/testtools/doc/hacking.rst

   1 =========================
   2 Contributing to testtools
   3 =========================
   4
   5 Coding style
   6 ------------
   7
   8 In general, follow `PEP 8`_ except where consistency with the standard
   9 library's unittest_ module would suggest otherwise.
  10
  11 testtools currently supports Python 2.6 and later, including Python 3.
  12
  13 Copyright assignment
  14 --------------------
  15
  16 Part of testtools raison d'etre is to provide Python with improvements to the
  17 testing code it ships. For that reason we require all contributions (that are
  18 non-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
  24 Please pick one of these and specify it when contributing code to testtools.
  25
  26
  27 Licensing
  28 ---------
  29
  30 All code that is not copyright assigned to Jonathan M. Lange (see Copyright
  31 Assignment above) needs to be licensed under the `MIT license`_ that testtools
  32 uses, so that testtools can ship it.
  33
  34
  35 Testing
  36 -------
  37
  38 Please write tests for every feature.  This project ought to be a model
  39 example of well-tested Python code!
  40
  41 Take particular care to make sure the *intent* of each test is clear.
  42
  43 You can run tests with ``make check``.
  44
  45 By default, testtools hides many levels of its own stack when running tests.
  46 This is for the convenience of users, who do not care about how, say, assert
  47 methods are implemented. However, when writing tests for testtools itself, it
  48 is 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
  52 Documentation
  53 -------------
  54
  55 Documents are written using the Sphinx_ variant of reStructuredText_.  All
  56 public methods, functions, classes and modules must have API documentation.
  57 When changing code, be sure to check the API documentation to see if it could
  58 be improved.  Before submitting changes to trunk, look over them and see if
  59 the manuals ought to be updated.
  60
  61
  62 Source layout
  63 -------------
  64
  65 The top-level directory contains the ``testtools/`` package directory, and
  66 miscellaneous files like ``README`` and ``setup.py``.
  67
  68 The ``testtools/`` directory is the Python package itself.  It is separated
  69 into submodules for internal clarity, but all public APIs should be “promoted”
  70 into the top-level package by importing them in ``testtools/__init__.py``.
  71 Users of testtools should never import a submodule in order to use a stable
  72 API.  Unstable APIs like ``testtools.matchers`` and
  73 ``testtools.deferredruntest`` should be exported as submodules.
  74
  75 Tests belong in ``testtools/tests/``.
  76
  77
  78 Committing to trunk
  79 -------------------
  80
  81 Testtools is maintained using bzr, with its trunk at lp:testtools. This gives
  82 every contributor the ability to commit their work to their own branches.
  83 However permission must be granted to allow contributors to commit to the trunk
  84 branch.
  85
  86 Commit access to trunk is obtained by joining the testtools-committers
  87 Launchpad team. Membership in this team is contingent on obeying the testtools
  88 contribution policy, see `Copyright Assignment`_ above.
  89
  90
  91 Code Review
  92 -----------
  93
  94 All code must be reviewed before landing on trunk. The process is to create a
  95 branch in launchpad, and submit it for merging to lp:testtools. It will then
  96 be reviewed before it can be merged to trunk. It will be reviewed by someone:
  97
  98 * not the author
  99 * a committer (member of the `~testtools-committers`_ team)
 100
 101 As a special exception, while the testtools committers team is small and prone
 102 to blocking, a merge request from a committer that has not been reviewed after
 103 24 hours may be merged by that committer. When the team is larger this policy
 104 will be revisited.
 105
 106 Code reviewers should look for the quality of what is being submitted,
 107 including conformance with this HACKING file.
 108
 109 Changes which all users should be made aware of should be documented in NEWS.
 110
 111
 112 NEWS management
 113 ---------------
 114
 115 The file NEWS is structured as a sorted list of releases. Each release can have
 116 a free form description and more or more sections with bullet point items.
 117 Sections in use today are 'Improvements' and 'Changes'. To ease merging between
 118 branches, the bullet points are kept alphabetically sorted. The release NEXT is
 119 permanently present at the top of the list.
 120
 121
 122 Release tasks
 123 -------------
 124
 125 #. Choose a version number, say X.Y.Z
 126 #. Branch from trunk to testtools-X.Y.Z
 127 #. In testtools-X.Y.Z, ensure __init__ has version ``(X, Y, Z, 'final', 0)``
 128 #. Replace NEXT in NEWS with the version number X.Y.Z, adjusting the reST.
 129 #. Possibly write a blurb into NEWS.
 130 #. Replace any additional references to NEXT with the version being
 131    released. (There should be none other than the ones in these release tasks
 132    which should not be replaced).
 133 #. Commit the changes.
 134 #. Tag the release, bzr tag testtools-X.Y.Z
 135 #. Run 'make release', this:
 136    #. Creates a source distribution and uploads to PyPI
 137    #. Ensures all Fix Committed bugs are in the release milestone
 138    #. Makes a release on Launchpad and uploads the tarball
 139    #. Marks all the Fix Committed bugs as Fix Released
 140    #. Creates a new milestone
 141 #. Merge the release branch testtools-X.Y.Z into trunk. Before the commit,
 142    add a NEXT heading to the top of NEWS and bump the version in __init__.py
 143    e.g. to ``(X, Y, Z+1, 'dev', 0)``.
 144 #. Push trunk to Launchpad
 145 #. If a new series has been created (e.g. 0.10.0), make the series on Launchpad.
 146
 147 .. _PEP 8: http://www.python.org/dev/peps/pep-0008/
 148 .. _unittest: http://docs.python.org/library/unittest.html
 149 .. _~testtools-committers: https://launchpad.net/~testtools-committers
 150 .. _MIT license: http://www.opensource.org/licenses/mit-license.php
 151 .. _Sphinx: http://sphinx.pocoo.org/
 152 .. _restructuredtext: http://docutils.sourceforge.net/rst.html
 153