lib/testtools/HACKING

   1 ===================================
   2 Notes for contributing to testtools
   3 ===================================
   4
   5 Coding style
   6 ------------
   7
   8 In general, follow PEP 8 <http://www.python.org/dev/peps/pep-0008/>.
   9
  10 For consistency with the standard library's ``unittest`` module, method names
  11 are generally ``camelCase``.
  12
  13 testtools supports Python 2.4 and later, so avoid any 2.5-only features like
  14 the ``with`` statement.
  15
  16
  17 Copyright assignment
  18 --------------------
  19
  20 Part of testtools raison d'etre is to provide Python with improvements to the
  21 testing code it ships. For that reason we require all contributions (that are
  22 non-trivial) to meet one of the following rules:
  23
  24  - be inapplicable for inclusion in Python.
  25  - be able to be included in Python without further contact with the
  26    contributor.
  27  - be copyright assigned to Jonathan M. Lange.
  28
  29 Please pick one of these and specify it when contributing code to testtools.
  30
  31
  32 Licensing
  33 ---------
  34
  35 All code that is not copyright assigned to Jonathan M. Lange (see Copyright
  36 Assignment above) needs to be licensed under the MIT license that testtools
  37 uses, so that testtools can ship it.
  38
  39
  40 Testing
  41 -------
  42
  43 Please write tests for every feature.  This project ought to be a model
  44 example of well-tested Python code!
  45
  46 Take particular care to make sure the *intent* of each test is clear.
  47
  48 You can run tests with ``make check``, or by running ``./run-tests`` directly.
  49
  50
  51 Source layout
  52 -------------
  53
  54 The top-level directory contains the ``testtools/`` package directory, and
  55 miscellaneous files like README and setup.py.
  56
  57 The ``testtools/`` directory is the Python package itself.  It is separated
  58 into submodules for internal clarity, but all public APIs should be “promoted”
  59 into the top-level package by importing them in ``testtools/__init__.py``.
  60 Users of testtools should never import a submodule, they are just
  61 implementation details.
  62
  63 Tests belong in ``testtools/tests/``.
  64
  65
  66 Commiting to trunk
  67 ------------------
  68
  69 Testtools is maintained using bzr, with its trunk at lp:testtools. This gives
  70 every contributor the ability to commit their work to their own branches.
  71 However permission must be granted to allow contributors to commit to the trunk
  72 branch.
  73
  74 Commit access to trunk is obtained by joining the testtools-devs Launchpad
  75 team. Membership in this team is contingent on obeying the testtools
  76 contribution policy, including assigning copyright of all the work one creates
  77 and places in trunk to Jonathan Lange.
  78
  79
  80 Code Review
  81 -----------
  82
  83 All code must be reviewed before landing on trunk. The process is to create a
  84 branch in launchpad, and submit it for merging to lp:testtools. It will then
  85 be reviewed before it can be merged to trunk. It will be reviewed by someone:
  86
  87  * not the author
  88  * a committer (member of the testtools-devs team)
  89
  90 As a special exception, while the testtools committers team is small and prone
  91 to blocking, a merge request from a committer that has not been reviewed after
  92 24 hours may be merged by that committer. When the team is larger this policy
  93 will be revisited.
  94
  95 Code reviewers should look for the quality of what is being submitted,
  96 including conformance with this HACKING file.
  97
  98 Changes which all users should be made aware of should be documented in NEWS.
  99
 100
 101 NEWS management
 102 ---------------
 103
 104 The file NEWS is structured as a sorted list of releases. Each release can have
 105 a free form description and more or more sections with bullet point items.
 106 Sections in use today are 'Improvements' and 'Changes'. To ease merging between
 107 branches, the bullet points are kept alphabetically sorted. The release NEXT is
 108 permanently present at the top of the list.
 109
 110
 111 Release tasks
 112 -------------
 113
 114 In no particular order:
 115
 116 * Choose a version number.
 117
 118 * Ensure __init__ has that version.
 119
 120 * Add a version number to NEWS immediately below NEXT.
 121
 122 * Possibly write a blurb into NEWS.
 123
 124 * Replace any additional references to NEXT with the version being released.
 125
 126 * Create a source distribution and upload to pypi ('make release').
 127
 128 * Upload to Launchpad as well.
 129
 130 * If a new series has been created (e.g. 0.10.0), make the series on Launchpad.
 131
 132 * Merge or push the release branch to trunk.
 133
 134 * Make a new milestone for the *next release*. We don't really know how we want
 135   to handle these yet, so this is a suggestion not actual practice:
 136
 137   * during release we rename NEXT to $version.
 138
 139   * we call new milestones NEXT.