[Python-checkins] devguide: Try to improve wording and explanations in the dev cycle
antoine.pitrou
python-checkins at python.org
Fri Feb 4 22:50:53 CET 2011
antoine.pitrou pushed c93b73417764 to devguide:
http://hg.python.org/devguide/rev/c93b73417764
changeset: 233:c93b73417764
tag: tip
user: Antoine Pitrou <solipsis at pitrou.net>
date: Fri Feb 04 22:50:39 2011 +0100
summary:
Try to improve wording and explanations in the dev cycle
files:
communication.rst
devcycle.rst
setup.rst
diff --git a/communication.rst b/communication.rst
--- a/communication.rst
+++ b/communication.rst
@@ -6,6 +6,8 @@
Python's development is communicated through a myriad of ways, mostly through
mailing lists, but also other forms.
+.. _mailinglists:
+
Mailing Lists
-------------
diff --git a/devcycle.rst b/devcycle.rst
--- a/devcycle.rst
+++ b/devcycle.rst
@@ -6,122 +6,150 @@
The responsibilities of a core developer shift based on what kind of branch of
Python a developer is working on and what stage the branch is in.
-To clarify terminology, Python uses a ``major.minor.micro.releaselevel``
-nomenclature for versions. So for Python 3.1.2 final, that is a major version
-of 3, a minor version of 1, a micro version of 2, and a release level (or
-stage) of "final".
+To clarify terminology, Python uses a ``major.minor.micro`` nomenclature
+for production-ready releases. So for Python 3.1.2 final, that is a *major
+version* of 3, a *minor version* of 1, and a *micro version* of 2.
+
+* new *major versions* are exceptional; they only come when strongly
+ incompatible changes are deemed necessary, and are planned very long
+ in advance;
+
+* new *minor versions* are feature releases; they get released roughly
+ every 18 months, from the current :ref:`in-development <indevbranch>`
+ branch;
+
+* new *micro versions* are bugfix releases; they get released roughly
+ every 6 months, although they can come more often if necessary; they are
+ prepared in :ref:`maintenance <maintbranch>` branches.
+
+We also publish non-final versions which get an additional qualifier:
+:ref:`alpha`, :ref:`beta`, :ref:`release candidate <rc>`. These versions
+are aimed at testing by advanced users, not production use.
Branches
''''''''
-Python has branches at the granularity of minor versions. Micro and
-release-level versions are represented using tags in the VCS.
+Different branches are used at a time to represent different *minor versions*
+in which development is made. All development should be done **first** in the
+:ref:`in-development <indevbranch>` branch, and selectively backported
+to other branches when necessary.
.. _indevbranch:
-In-Development
---------------
+In-development (main) branch
+----------------------------
-The current branch under active development. It can be :ref:`checked out
-<checkout>` from http://svn.python.org/projects/python/branches/py3k.
+The branch for the next minor version; it is under active development for
+all kinds of changes: new features, semantic changes, performance improvements,
+bug fixes. It can be :ref:`checked out <checkout>` from
+http://svn.python.org/projects/python/branches/py3k.
-The in-development branch is where new functionality and semantic changes
-occur. Currently this branch is known as the "py3k" branch. The next minor
-release of Python will come from this branch (major releases are once a decade
-and so have no specific rules on how they are started). All changes land in this
-branch and then trickle down to other branches.
+Once a :ref:`final` release is made from the in-development branch (say, 3.2), a
+new :ref:`maintenance branch <maintbranch>` (e.g. ``release32-maint``)
+is created to host all bug fixing activity for further micro versions
+(3.2.1, 3.2.2, etc.).
-Once a Final_ release is made from the in-development branch, a branch is made
-to represent the minor version of Python and it goes into maintenance mode.
-Typically a minor version of Python is under development for about 18 months.
+.. _maintbranch:
-Maintenance
------------
+Maintenance branches
+--------------------
-The branch currently being maintained for bug fixes.
+A branch currently being maintained for bug fixes. There are currently
+two of them in activity: one for Python 3.x and one for Python 2.x. At
+some point in the future, Python 2.x will be closed for bug fixes and there
+will be only one maintenance branch left.
-The branch under maintenance is the last minor version of Python to be released
-as Final_. This means if the latest release of Python was 3.1.2, then the
-branch representing Python 3.1 is in maintenance mode.
+The only changes allowed to occur in a maintenance branch without debate are
+bug fixes. Also, a general rule for maintenance branches is that compatibility
+must not be broken at any point between sibling minor releases (3.1.1, 3.1.2,
+etc.). For both rules, only rare exceptions are accepted and **must** be
+discussed first.
-The only changes allowed to occur in a maintenance branch without debate are bug
-fixes.
-Semantic changes **must** be carefully considered as code out in the world will
-have already been developed that will rely on the released semantics. Changes
-related to semantics should be discussed on python-dev before being made.
+When a new maintenance branch is created (after a new *minor version* is
+released), the old maintenance branch on that major version (e.g. 3.1.x
+after 3.2 gets released) goes into :ref:`security mode <secbranch>`.
-A branch stays in maintenance mode as long as a new minor release has not been
-made. For example, this means that Python 2.6 stayed in maintenance mode until
-Python 2.7.0 was released, at which point 2.7 went into maintenance mode and
-2.6 went into Security_ mode. As new minor releases occur on a (roughly) 18
-month schedule, a branch stays in maintenance mode for the same amount of time.
-A micro release of a maintenance branch is made about every six months.
-Typically when a new minor release is made one more release of the new-old
-version of Python is made.
+.. _secbranch:
+Security branches
+-----------------
-Security
---------
-A branch less than five years old but no longer in maintenance mode.
+A branch less than 5 years old but no longer in maintenance mode.
-The only changes made to a branch that is being maintained for security
-purposes are somewhat obviously those related to security, e.g., privilege
-escalation, and issues that lead to crashes. Other behavioral issues are
-**not** considered a
-security risk and thus not backported to a branch being maintained for
-security. Any release made from a branch under security maintenance is
-source-only and done only when actual security patches have been applied to the
-branch.
+The only changes made to a security branch are those fixing issues exploitable
+by attackers such as crashes, privilege escalation and, optionally, other
+issues such as denial of service attacks. Other behavioral issues are
+**not** considered a security risk and thus not backported to a security branch.
+Any release made from a security branch is source-only and done only when
+actual security patches have been applied to the branch.
+.. _stages:
+
Stages
''''''
-Based on what stage the in-development version of Python is in, the
-responsibilities of a core developer change in regards to commits to the VCS.
+Based on what stage the :ref:`in-development <indevbranch>` version of Python
+is in, the responsibilities of a core developer change in regards to commits
+to the VCS.
Pre-alpha
---------
-This is the stage a branch is in from the last final release until the first
-alpha (a1). There are no special restrictions placed on commits beyond those
-imposed by the type of branch being worked on (e.g., in-development vs.
-maintenance).
+The branch is in this stage when no official release has been done since
+the latest final release. There are no special restrictions placed on
+commits, although the usual advice applies (getting patches reviewed, avoiding
+breaking the buildbots).
+
+.. _alpha:
Alpha
-----
-Alphas typically serve as a reminder to core developers that they need to start
-getting in changes that change semantics or add something to Python as such
-things should not be added during a Beta_. Otherwise no new restrictions are in
-place while in alpha.
+Alpha releases typically serve as a reminder to core developers that they
+need to start getting in changes that change semantics or add something to
+Python as such things should not be added during a Beta_. Otherwise no new
+restrictions are in place while in alpha.
+
+.. _beta:
Beta
----
-A branch in beta means that no new additions to Python are accepted. Bugfixes
-and the like are still fine. Being in beta can be viewed much like being in RC_
-but without the extra overhead of needing commit reviews.
+After a first beta release is published, no new features are accepted. Only
+bug fixes can now be committed. This is when core developers should concentrate
+on the task of fixing regressions and other new issues filed by users who have
+downloaded the alpha and beta releases.
-.. _RC:
+Being in beta can be viewed much like being in RC_ but without the extra overhead
+of needing commit reviews.
+
+.. _rc:
Release Candidate (RC)
----------------------
+
A branch preparing for an RC release can only have bugfixes applied that have
-been reviewed by other core developers. That reviewer should make a post to the
-issue related to the change and be mentioned in the commit message.
+been reviewed by other core developers. Generally, these issues must be
+severe enough (e.g. crashes) that they deserve fixing before the final release.
+All other issues should be deferred to the next development cycle, since stability
+is the strongest concern at this point.
You **cannot** skip the peer review during an RC, no matter how small! Even if
it is a simple copy-and-paste change, **everything** requires peer review from
a core developer.
+.. _final:
Final
-----
+
When a final release is being cut, only the release manager (RM) can make
-changes to the branch.
+changes to the branch. After the final release is published, the full
+:ref:`development cycle <stages>` starts again for the next minor version.
+
diff --git a/setup.rst b/setup.rst
--- a/setup.rst
+++ b/setup.rst
@@ -40,8 +40,8 @@
svn co http://svn.python.org/projects/python/branches/py3k
If you want a read-only checkout of an already-released version of Python,
-i.e., a version in maintenance mode, run something like the following which
-gets you a checkout for Python 3.1::
+i.e., a version in :ref:`maintenance mode <maintbranch>`, run something
+like the following which gets you a checkout for Python 3.1::
svn co http://svn.python.org/projects/python/branches/release31-maint
--
Repository URL: http://hg.python.org/devguide
More information about the Python-checkins
mailing list