[Python-checkins] devguide: Issue #15260: Expand information on Misc/NEWS entries.

[ned.deily]

http://hg.python.org/devguide/rev/bbe197bf57a1
changeset:   529:bbe197bf57a1
user:        Ned Deily <nad at acm.org>
date:        Fri Jul 06 18:24:45 2012 -0700
summary:
  Issue #15260: Expand information on Misc/NEWS entries.
(Patch by Chris Jerdonek)

files:
  committing.rst |  50 ++++++++++++++++++++++++-------------
  1 files changed, 32 insertions(+), 18 deletions(-)


diff --git a/committing.rst b/committing.rst
--- a/committing.rst
+++ b/committing.rst
@@ -43,8 +43,38 @@
 making a complete patch.
 
 
-Commit Messages and NEWS Entries
---------------------------------
+NEWS Entries
+------------
+
+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.
+
+New NEWS entries are customarily added at or near the top of their
+respective sections, so that entries within a section appear in approximate
+order from newest to oldest.  However, this is customary and not a
+requirement.
+
+A nice trick to make Mercurial’s automatic file merge work more smoothly
+is to put a new entry after the first or first two entries rather than
+at the very top.  This way if you commit, pull new changesets and merge,
+the merge will succeed automatically.
+
+
+Commit Messages
+---------------
 
 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
@@ -67,22 +97,6 @@
 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.
-
 Mercurial hooks
 '''''''''''''''
 

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