/usr/share/doc/python-testtools/html/hacking.html is in python-testtools 0.9.14-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Contributing to testtools — testtools vVERSION documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: 'VERSION',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="testtools vVERSION documentation" href="index.html" />
<link rel="next" title="testtools NEWS" href="news.html" />
<link rel="prev" title="testtools for framework folk" href="for-framework-folk.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="news.html" title="testtools NEWS"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="for-framework-folk.html" title="testtools for framework folk"
accesskey="P">previous</a> |</li>
<li><a href="index.html">testtools vVERSION documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="contributing-to-testtools">
<h1>Contributing to testtools<a class="headerlink" href="#contributing-to-testtools" title="Permalink to this headline">¶</a></h1>
<div class="section" id="coding-style">
<h2>Coding style<a class="headerlink" href="#coding-style" title="Permalink to this headline">¶</a></h2>
<p>In general, follow <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP 8</a> except where consistency with the standard
library’s <a class="reference external" href="http://docs.python.org/library/unittest.html">unittest</a> module would suggest otherwise.</p>
<p>testtools supports Python 2.4 and later, including Python 3, so avoid any
2.5-only features like the <tt class="docutils literal"><span class="pre">with</span></tt> statement.</p>
</div>
<div class="section" id="copyright-assignment">
<h2>Copyright assignment<a class="headerlink" href="#copyright-assignment" title="Permalink to this headline">¶</a></h2>
<p>Part of testtools raison d’etre is to provide Python with improvements to the
testing code it ships. For that reason we require all contributions (that are
non-trivial) to meet one of the following rules:</p>
<ul class="simple">
<li>be inapplicable for inclusion in Python.</li>
<li>be able to be included in Python without further contact with the contributor.</li>
<li>be copyright assigned to Jonathan M. Lange.</li>
</ul>
<p>Please pick one of these and specify it when contributing code to testtools.</p>
</div>
<div class="section" id="licensing">
<h2>Licensing<a class="headerlink" href="#licensing" title="Permalink to this headline">¶</a></h2>
<p>All code that is not copyright assigned to Jonathan M. Lange (see Copyright
Assignment above) needs to be licensed under the <a class="reference external" href="http://www.opensource.org/licenses/mit-license.php">MIT license</a> that testtools
uses, so that testtools can ship it.</p>
</div>
<div class="section" id="testing">
<h2>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2>
<p>Please write tests for every feature. This project ought to be a model
example of well-tested Python code!</p>
<p>Take particular care to make sure the <em>intent</em> of each test is clear.</p>
<p>You can run tests with <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt>.</p>
<p>By default, testtools hides many levels of its own stack when running tests.
This is for the convenience of users, who do not care about how, say, assert
methods are implemented. However, when writing tests for testtools itself, it
is often useful to see all levels of the stack. To do this, add
<tt class="docutils literal"><span class="pre">run_tests_with</span> <span class="pre">=</span> <span class="pre">FullStackRunTest</span></tt> to the top of a test’s class definition.</p>
</div>
<div class="section" id="documentation">
<h2>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h2>
<p>Documents are written using the <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> variant of <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>. All
public methods, functions, classes and modules must have API documentation.
When changing code, be sure to check the API documentation to see if it could
be improved. Before submitting changes to trunk, look over them and see if
the manuals ought to be updated.</p>
</div>
<div class="section" id="source-layout">
<h2>Source layout<a class="headerlink" href="#source-layout" title="Permalink to this headline">¶</a></h2>
<p>The top-level directory contains the <tt class="docutils literal"><span class="pre">testtools/</span></tt> package directory, and
miscellaneous files like <tt class="docutils literal"><span class="pre">README</span></tt> and <tt class="docutils literal"><span class="pre">setup.py</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">testtools/</span></tt> directory is the Python package itself. It is separated
into submodules for internal clarity, but all public APIs should be “promoted”
into the top-level package by importing them in <tt class="docutils literal"><span class="pre">testtools/__init__.py</span></tt>.
Users of testtools should never import a submodule in order to use a stable
API. Unstable APIs like <tt class="docutils literal"><span class="pre">testtools.matchers</span></tt> and
<tt class="docutils literal"><span class="pre">testtools.deferredruntest</span></tt> should be exported as submodules.</p>
<p>Tests belong in <tt class="docutils literal"><span class="pre">testtools/tests/</span></tt>.</p>
</div>
<div class="section" id="committing-to-trunk">
<h2>Committing to trunk<a class="headerlink" href="#committing-to-trunk" title="Permalink to this headline">¶</a></h2>
<p>Testtools is maintained using bzr, with its trunk at lp:testtools. This gives
every contributor the ability to commit their work to their own branches.
However permission must be granted to allow contributors to commit to the trunk
branch.</p>
<p>Commit access to trunk is obtained by joining the testtools-committers
Launchpad team. Membership in this team is contingent on obeying the testtools
contribution policy, see <a class="reference internal" href="#copyright-assignment">Copyright Assignment</a> above.</p>
</div>
<div class="section" id="code-review">
<h2>Code Review<a class="headerlink" href="#code-review" title="Permalink to this headline">¶</a></h2>
<p>All code must be reviewed before landing on trunk. The process is to create a
branch in launchpad, and submit it for merging to lp:testtools. It will then
be reviewed before it can be merged to trunk. It will be reviewed by someone:</p>
<ul class="simple">
<li>not the author</li>
<li>a committer (member of the <a class="reference external" href="https://launchpad.net/~testtools-committers">~testtools-committers</a> team)</li>
</ul>
<p>As a special exception, while the testtools committers team is small and prone
to blocking, a merge request from a committer that has not been reviewed after
24 hours may be merged by that committer. When the team is larger this policy
will be revisited.</p>
<p>Code reviewers should look for the quality of what is being submitted,
including conformance with this HACKING file.</p>
<p>Changes which all users should be made aware of should be documented in NEWS.</p>
</div>
<div class="section" id="news-management">
<h2>NEWS management<a class="headerlink" href="#news-management" title="Permalink to this headline">¶</a></h2>
<p>The file NEWS is structured as a sorted list of releases. Each release can have
a free form description and more or more sections with bullet point items.
Sections in use today are ‘Improvements’ and ‘Changes’. To ease merging between
branches, the bullet points are kept alphabetically sorted. The release NEXT is
permanently present at the top of the list.</p>
</div>
<div class="section" id="release-tasks">
<h2>Release tasks<a class="headerlink" href="#release-tasks" title="Permalink to this headline">¶</a></h2>
<ol class="arabic simple">
<li>Choose a version number, say X.Y.Z</li>
<li>Branch from trunk to testtools-X.Y.Z</li>
<li>In testtools-X.Y.Z, ensure __init__ has version <tt class="docutils literal"><span class="pre">(X,</span> <span class="pre">Y,</span> <span class="pre">Z,</span> <span class="pre">'final',</span> <span class="pre">0)</span></tt></li>
<li>Replace NEXT in NEWS with the version number X.Y.Z, adjusting the reST.</li>
<li>Possibly write a blurb into NEWS.</li>
<li>Replace any additional references to NEXT with the version being
released. (There should be none other than the ones in these release tasks
which should not be replaced).</li>
<li>Commit the changes.</li>
<li>Tag the release, bzr tag testtools-X.Y.Z</li>
<li>Run ‘make release’, this:
#. Creates a source distribution and uploads to PyPI
#. Ensures all Fix Committed bugs are in the release milestone
#. Makes a release on Launchpad and uploads the tarball
#. Marks all the Fix Committed bugs as Fix Released
#. Creates a new milestone</li>
<li>Merge the release branch testtools-X.Y.Z into trunk. Before the commit,
add a NEXT heading to the top of NEWS and bump the version in __init__.py.
Push trunk to Launchpad</li>
<li>If a new series has been created (e.g. 0.10.0), make the series on Launchpad.</li>
</ol>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Contributing to testtools</a><ul>
<li><a class="reference internal" href="#coding-style">Coding style</a></li>
<li><a class="reference internal" href="#copyright-assignment">Copyright assignment</a></li>
<li><a class="reference internal" href="#licensing">Licensing</a></li>
<li><a class="reference internal" href="#testing">Testing</a></li>
<li><a class="reference internal" href="#documentation">Documentation</a></li>
<li><a class="reference internal" href="#source-layout">Source layout</a></li>
<li><a class="reference internal" href="#committing-to-trunk">Committing to trunk</a></li>
<li><a class="reference internal" href="#code-review">Code Review</a></li>
<li><a class="reference internal" href="#news-management">NEWS management</a></li>
<li><a class="reference internal" href="#release-tasks">Release tasks</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="for-framework-folk.html"
title="previous chapter">testtools for framework folk</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="news.html"
title="next chapter">testtools NEWS</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/hacking.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="news.html" title="testtools NEWS"
>next</a> |</li>
<li class="right" >
<a href="for-framework-folk.html" title="testtools for framework folk"
>previous</a> |</li>
<li><a href="index.html">testtools vVERSION documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010, The testtools authors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.
</div>
</body>
</html>
|