[Python-Dev] Documenting branch policy

[Greg Ward]

[cc'ing pydotorg since this involves a change to web content, but
followup to python-dev please]

Has anyone taken the time to sit down and document the development
process surrounding release and maintenance branches?  Speaking as an
infrequent contributor to Python, it's never been entirely clear to me
how to deal with branches.  Seems to me like adding a paragraph or two
to this page:

  http://www.python.org/dev/process.html

would be a good start.  Here's a first crack, based largely on
guesswork, extrapolation from my day job (which also uses maintenance
branches), and common sense:

"""
<h4>CVS Branch Policy</h4>

<p>The Python development process uses CVS branches for a couple
of purposes:
<ul>
  <li>maintenance branches, for minor Python releases (2.2.3, 2.3.1,
      etc.)
  <li>release branches, for the exclusive use of the release manager(s)
  <li>feature branches, for large, disruptive additions/changes that take
      a long time to stabilize
</ul>

<h5>Maintenance branches</h5>

<p>Every major Python version (2.1, 2.2, 2.3, etc.) is accompanied by a
<em>maintenance branch</em>.  Minor Python releases are always made from
a maintenance branch -- e.g. Python 2.2.3 was made on the
<code>release22-maint</code> branch, and Python 2.3.1 will be made on
<code>release23-maint</code>.  Maintenance branches are long-lived; they
remain open as long as minor releases based on the corresponding
major release are a possibility.  Maintenance branches are for bug fixes
<em>only</em>; maintaining backwards compatibility at every level is
imperative.  (In particular, all extension modules and bytecode for
Python 2.<em>x</em>.<em>y</em> must continue to work with Python
2.<em>x</em>.<em>y+1</em> -- binary compatibility in the C API and
bytecode must be maintained.)</p>

<p>Any Python developer may checkin bug fixes on a maintenance branch;
it is the release manager's responsibility to create the maintenance
branch after releasing a new major Python version.</p>

<h5>Release branches</h5>

<p>Every release up to and including the final release for a new major
Python version is accompanied by a <em>release branches</em>.  For
example, there were release branches for 2.3a1, 2.3a2, 2.3b1, 2.3b2,
2.3c1, and 2.3 itself; there will <em>not</em> be release branches for
2.3.1, 2.3.2, and so forth.  Release branches allow the release manager
to make small, last-minute changes without being affected by mainline
development.  It is the release manager's responsibility to merge
changes from each release branch back onto the trunk after the release
is finished.

<p>Unless you are one of the release managers for a new major Python
version, you should have nothing to do with release branches.</p>

<h5>Feature branches</h5>

<p>Occasionally, a new feature will be deemed large and disruptive
enough that it will be added on a branch.  For example, the "new-style
classes" feature of Python 2.2 was added on <code>descr-branch</code>
(the non-obvious name stems from <em>descriptors</em>, the new C-level
data structure underlying new-style classes), which took several months
to stabilize before it was merged onto the trunk.  Managing a feature
branch is tricky business, and the longer it takes to stabilize the new
feature, the trickier it gets.

<p>Feature branches are generally created and used by a single
developer.  Do not create a feature branch without discussing it on
python-dev.</p>
"""

Please let me know how close this is to describing reality!

        Greg
-- 
Greg Ward <gward at python.net>                         http://www.gerg.ca/
Cheops' Law: Nothing *ever* gets built on schedule or within budget.