[Python-checkins] devguide: Update NEWS entry policy based on recent mailing list discussion and forward

[nick.coghlan]

http://hg.python.org/devguide/rev/0541f815d016
changeset:   457:0541f815d016
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Sun Oct 23 21:04:21 2011 +1000
summary:
  Update NEWS entry policy based on recent mailing list discussion and forward porting section based on Issue 13105

files:
  committing.rst |  27 ++++++++++++++++++++++++++-
  1 files changed, 26 insertions(+), 1 deletions(-)


diff --git a/committing.rst b/committing.rst
--- a/committing.rst
+++ b/committing.rst
@@ -28,8 +28,8 @@
 making a complete patch.
 
 
-Commit Messages
----------------
+Commit Messages and NEWS Entries
+--------------------------------
 
 Every commit has a commit message to document why a change was made and to
 communicate that reason to other core developers. Python core developers have
@@ -52,6 +52,22 @@
 understands the justification for the change).  Also, if a non-core developer
 contributed to the resolution, it is good practice to credit them.
 
+Almost all changes made to the code base deserve an entry in ``Misc/NEWS``.
+The ``What's New in Python`` document is the place for more subjective
+judgments of the "importance" of changes. There are two notable exceptions
+to this general principle, and they both relate to changes that *already*
+have a NEWS entry, and have not yet been included in any formal release
+(including alpha and beta releases). These exceptions are:
+
+* If a change is reverted prior to release, then the corresponding entry
+  is simply removed. Otherwise, a new entry must be added noting that the
+  change has been reverted (e.g. when a feature is released in an alpha and
+  then cut prior to the first beta)
+
+* If a change is a fix or other adjustment to an earlier unreleased change
+  and the original NEWS entry remains valid, then no additional entry is
+  needed.
+
 
 Working with Mercurial_
 -----------------------
@@ -192,6 +208,14 @@
 the :abbr:`DAG (directed acyclic graph)` used by hg to work with the movement of
 the patch through the codebase instead of against it.
 
+Note that this policy applies only within a major version - the ``2.7`` branch
+is an independent thread of development, and should *never* be merged to any
+of the ``3.x`` branches of ``default``. If a bug fix applies to both ``2.x``
+and ``3.x``, the two additions are handled as separate commits. It doesn't
+matter which is updated first, but any associated tracker issues should be
+closed only after all affected versions have been modified in the main
+repository.
+
 .. warning::
    Even when porting an already committed patch, you should **still** check the
    test suite runs successfully before committing the patch to another branch.

-- 
Repository URL: http://hg.python.org/devguide