updates

pep-0101.txt

@@ -44,40 +44,74 @@ How to Make A Release
     "releaseXY-fork".  If a micro release number is used, then we'll
     say X.Y.MaZ.
 
-  ___ At noon the day before the release, create a branch for X.YaZ.
+    Note: This document has been updated to reflect the more
+    streamlined procedures used to release Python 2.3 (including the
+    alphas and betas).
 
-      All Python development happens on the trunk.  Making releases
+  ___ Impose a check-in freeze.  Send a message to
-      from a branch allows development by the community to continue
+      python-dev@python.org telling people not to make any check-ins
-      without impacting what ends up in the release.  There's a
+      on the tree until further notice.
-      natural tension here though: branching too soon causes headaches
-      when the branch has to be merged back into the trunk, while
-      branching too late can cause dependency problems with
-      documentation and Windows release steps.
 
-      The compromise is to create the branch at noon, local time, the
+      At this point, nobody except the RM should make any commits to
-      day before the release.  This should give enough time to Fred to
+      the branch (or his duly assigned agents, i.e. Guido the BDFL,
-      make the documentation, then for Tim to create the Windows
+      Fred Drake for documentation, or Tim Peters for Windows).  If
-      installer, both of which need to happen before the release can
+      the RM screwed up and some desperate last minute change to the
-      be announced.  It's also short enough that hopefully not too
+      branch is necessary, it can mean extra work for Fred and Tim.
-      many trunk changes will need to be merged into the branch, or
+      So try to avoid this!
-      vice versa.
 
-      Once the branch is made, only the RM or his appointed bots are
+  ___ Log into irc.freenode.net and join the #python-dev channel.
-      allowed to make commits to the branch.  You can assume that Fred
-      is a bot for the Doc/ tree, Tim is a bot for the Windows stuff,
-      and Jack is a bot for Mac stuff.
 
-      Anyone can continue to make checkins on the trunk, but if such a
+      You probably need to coordinate with other people around the
-      change should be merged into the branch, the committer must
+      world.  This IRC channel is where we've arranged to meet.
-      indicate this in the checkin message.  It is the responsibility
-      of the RM to decide on a case-by-case basis which trunk
-      modifications should be merged into the branch.
 
-      To create a branch the following steps are taken:
+  ___ The most important thing to do is to update the Misc/NEWS file.
+      Tim will need this in order to do the Windows release and he
+      likes to stay up late.  This step can be pretty tedious, so it's
+      best to get to it immediately after making the branch, or even
+      before you've made the branch.
+
+      Add high level items new to this release.  E.g. if we're
+      releasing 2.2a3, there must be a section at the top of the file
+      explaining "What's new in Python 2.2a3".  It will be followed by
+      a section entitled "What's new in Python 2.2a2".
+
+      Note that you /hope/ that as developers add new features to the
+      trunk, they've updated the NEWS file accordingly.  You can't be
+      positive, so double check.  If you're a Unix weenie, it helps to
+      verify with Tim Peters about changes on Windows, and Jack Jansen
+      about changes on the Mac.
+
+      This command should help you:
+
+      % cvs log | python Tools/scripts/logmerge.py > /tmp/news.txt
+
+      IOW, you're printing out all the cvs log entries from the
+      previous release until now.  You can then troll through the
+      news.txt file looking for interesting things to add to NEWS.
+
+  ___ Tag and/or branch the tree for release X.YaZ
+
+      If you're releasing an alpha/beta/release candidate, you will
+      just tag the tree.  If you are releasing a final release, you
+      will tag and create a branch.
+
+      All Python development happens on the trunk.  While it's
+      sometimes challenging to keep people from checking things in
+      while you're making a release, it's still preferred to creating
+      a short-lived release branch.
+
+      Practically speaking, we tag and branch just before making the
+      release.  Tagging too early causes too much merging work.
 
     ___ Do a CVS update with the -A, -d, and -P flags, e.g.
         % cvs -q update -d -P -A
 
+      To tag the tree, do the following:
+
+    ___ cvs tag rXYaZ
+
+      To create a branch the following steps are taken:
+
     ___ CVS tag the trunk with the symbolic name "rXYaZ-fork", e.g.
         % cvs tag r22a3-fork
 
@@ -87,30 +121,19 @@ How to Make A Release
     ___ Check out a clean version of the branch into a new directory.
         You'll be doing a lot of work in this directory and you want
         to keep it straight from your trunk working directory.  E.g.
-        % cvs -d <cvsroot> -q co -d python-22a3 -r r22a3-branch python/dist/src
 
-  ___ Send an email to python-dev@python.org indicating the fork and
+        % export CVSROOT=cvs.sf.net:/cvsroot/python
-      branch tags you've just created.
+        % cvs -q co -d python-22a3 -r r22a3-branch python/dist/src
 
-  ___ Put a freeze on check ins into the branch.  At this point,
+    ___ cd into the branch directory.
-      nobody except the RM should make any commits to the branch (or
-      his duly assigned agents, i.e. Guido the BDFL, Fred Drake for
-      documentation, or Tim Peters for Windows).  If the RM screwed up
-      and some desperate last minute change to the branch is
-      necessary, it can mean extra work for Fred and Tim.  So try to
-      avoid this!
 
-  ___ In the branch, change Include/patchlevel.h in two places, to
+  ___ Change Include/patchlevel.h in two places, to
       reflect the new version number you've just created.  You'll want
       to change the PY_VERSION macro, and one or several of the
       version subpart macros just above PY_VERSION, as appropriate.
 
-  ___ If you're changing the version number for Python (e.g. from
+  ___ Update the README file, which has a big banner at the top
-      Python 2.1.1 to Python 2.1.2), you also need to update the
+      proclaiming its identity.
-      README file, which has a big banner at the top proclaiming its
-      identity.  Don't do this if you're just releasing a new alpha or
-      beta release, but /do/ do this if you're release a new micro
-      release.
 
     ___ There's also a mention of the version in
         Doc/texinputs/boilerplate.tex; Fred usually takes care of that.
@@ -148,106 +171,59 @@ How to Make A Release
   ___ For a final release, edit the first paragraph of 
       Doc/whatsnew/whatsnewXX.tex to include the actual release date;
       e.g. "Python 2.3 was released on August 1, 2003."  
-      There's no need to edit this for alpha or beta releases.
+      There's no need to edit this for alpha or beta releases.  Note
+      that Andrew often takes care of this.
 
-  ___ For the next few hours, selectively merge stuff from trunk into
+  ___ By now, Fred has created the HTML for the documentation and
-      branch.  For each change you see on the trunk (i.e. via the
+      pushed the appropriate files out to www.python.org.  Tim needs
-      python-checkins mailing list), you need to decide whether the
+      this to build the Windows installer, but the RM doesn't need
-      change should also be applied to the branch.
+      this stuff to build the source distribution.
 
-      There is a tension here.  Announcing the branch often jogs
+      Fred tells Tim Peters where the documentation file is.  This may
-      people's natural tendency to procrastinate so some very useful
+      generate some last minute changes on the branch.  Once Fred is
-      patches end up getting checked in at the last moment.  But the
+      done, there can be no further checkins on the branch in the Doc/
-      Windows and Docs releases tend to be built many hours before the
+      directory -- not even by the RM.  For final releases, Fred also
-      source release, and changes to the branch can force a lot of
+      sends email to Milan Zamazal for conversion to the GNU Info
-      wasted effort to rebuild them.  The best advice is to be
+      format, and to Hernan M. Foffani for conversion to HTML Help.
-      judicious and to consult Fred and Tim before adding anything
-      big.  You really want to avoid skew between the various platform
-      releases.
 
-      Note that committers of changes to the trunk SHOULD include in
-      the checkin message, a note indicating the suitability of their
-      patch for the branch.
-
-      If so, it's fairly easy to apply the change by diff'ing the file
-      and patching it manually.  You can also sometimes get away with
-      just copying the file from the trunk directory to the branch
-      directory, but be careful so you don't lose changes that only
-      exist in the branch!
-
-  ___ After creating the branch, the most important thing to do next
-      is to update the Misc/NEWS file.  Tim will need this in order to
-      do the Windows release and he likes to stay up late.  This step
-      can be pretty tedious, so it's best to get to it immediately
-      after making the branch, or even before you've made the branch.
-      The sooner the better (but again, watch for new checkins up
-      until the release is made!)
-
-      Add high level items new to this release.  E.g. if we're
-      releasing 2.2a3, there must be a section at the top of the file
-      explaining "What's new in Python 2.2a3".  It will be followed by
-      a section entitled "What's new in Python 2.2a2".
-
-      Note that you /hope/ that as developers add new features to the
-      trunk, they've updated the NEWS file accordingly.  You can't be
-      positive, so double check.  If you're a Unix weenie, it helps to
-      verify with Tim Peters about changes on Windows, and Jack Jansen
-      about changes on the Mac.
-
-      This command should help you:
-
-      % cvs log -rr22a1: | python Tools/scripts/logmerge.py > /tmp/news.txt
-
-      IOW, you're printing out all the cvs log entries from the
-      previous release until now.  You can then troll through the
-      news.txt file looking for interesting things to add to NEWS.
-
-  ___ Check your NEWS changes into the branch and into the trunk.
-
-  ___ Once the branch is frozen, Fred Drake needs to create the HTML
-      from the documentation.  He does this and uploads the file to
-      www.python.org.  Then he tells Tim Peters where this file is.
-      This may generate some last minute changes on the branch.  Once
-      Fred is done, there can be no further checkins on the branch in
-      the Doc/ directory -- not even by the RM.  For final releases,
-      Fred also sends email to Milan Zamazal for conversion to the GNU
-      Info format, and to Hernan M. Foffani for conversion to HTML
-      Help.
-
-      Note that Fred is responsible both for merging doc changes from
-      the trunk to the branch AND for merging any branch changes from
-      the branch to the trunk during the cleaning up phase.
       Basically, if it's in Doc/, Fred will take care of it.
 
   ___ Tim Peters grabs the HTML and uses this to build the Windows
       installer.
 
   ___ Tim performs his Windows magic, generating an installer
-      executable.  He uploads this file to python.org, and then sends
+      executable.  He uploads this file to SourceForge, and then sends
       the RM a notice which includes the location and MD5 checksum of
       the Windows executable.
 
+      Note that Tim used to upload the installer to www.python.org,
+      but has had problems with ssh for a while now.
+
       Note that Tim's creation of the Windows executable may generate
       a few more commits on the branch.  Tim will be responsible for
       merging Windows-specific changes from trunk to branch, and from
       branch to trunk.
 
-  ___ It's Noon!
+  ___ Download the Windows executable from SourceForge to
+      creosote.python.org.  Tell Tim so he can remove the file from
+      SourceForge.
 
-      Now, you're ready to build the source tarball.  First cd to your
+  ___ Time to build the source tarball.  If you created a branch, be
-      working directory for the branch.  E.g.
+      sure to cd to your working directory for the branch.  E.g.
       % cd .../python-22a3
 
-  ___ Do a "cvs update" in this directory.  Do NOT include the -A flag!
+  ___ Do a "cvs update" in this directory.  Do NOT include the -A flag
+      if you're working on a branch, but do include it if you're
+      working on the trunk.
 
       You should not see any "M" files, but you may see several "P"
       files.  I.e. you better not have any uncommitted changes in your
       working directory, but you may pick up some of Fred's or Tim's
       last minute changes.
 
-  ___ Now tag the branch using a symbolic name like "rXYaZ",
+  ___ If you've seen updates to existing files, update the cvs tag:
-      e.g. r22a3
+
-      % cvs tag r22a3
+      % cvs tag -F r22a3
 
   ___ Change to a neutral directory, i.e. one in which you can do a
       fresh, virgin, cvs export of the branch.  You will be creating a
@@ -255,16 +231,19 @@ How to Make A Release
       a CVS export of the tagged branch.
 
       % cd ~
-      % cvs -d <cvsroot> export -rr22a3 -d Python-2.2a3 python/dist/src
+      % export CVSROOT=cvs.sf.net:/cvsroot/python
+      % cvs export -rr23c2 -d Python-2.3c2 python/dist/src
 
   ___ Generate the tarball.  Note that we're not using the `z' option
       on the tar command because 1) that's only supported by GNU tar
       as far as we know, and 2) we're going to max out the compression
       level, which isn't a supported option.
-      % tar cf - Python-2.2a2 | gzip -9 > Python-2.2a2.tgz
+
+      % tar cf - Python-2.3c2 | gzip -9 > Python-2.3c2.tgz
 
   ___ Calculate the MD5 checksum of the tgz file you just created
-      % md5sum Python-2.2a2.tgz
+
+      % md5sum Python-2.3c2.tgz
 
       Note that if you don't have the md5sum program, there is a
       Python replacement in the Tools/scripts/md5sum.py file.
@@ -275,8 +254,8 @@ How to Make A Release
       steps to take:
 
       % cd /tmp
-      % tar zxvf ~/Python-2.2a3.tgz
+      % tar zxvf ~/Python-2.3c2.tgz
-      % cd Python-2.2a3
+      % cd Python-2.3c2
       % ls
       (Do things look reasonable?)
       % ./configure