Mercurial > peps
changeset 3873:38f77ef60e03
This should be most of the edits needed for releasing from hg.
| author | Georg Brandl <georg@python.org> |
|---|---|
| date | Sun, 08 May 2011 11:14:12 +0200 |
| parents | b9390aa12855 |
| children | 0c3788b45afc |
| files | pep-0101.txt |
| diffstat | 1 files changed, 140 insertions(+), 169 deletions(-) [+] |
line wrap: on
line diff
--- a/pep-0101.txt +++ b/pep-0101.txt @@ -27,15 +27,14 @@ Abstract How to Make A Release - Here are the steps taken to make a Python release. Some steps are - more fuzzy than others because there's little that can be - automated (e.g. writing the NEWS entries). Where a step is - usually performed by An Expert, the role of that expert is given. - Otherwise, assume the step is done by the Release Manager (RM), - the designated person performing the release. The roles and their - current experts are: + Here are the steps taken to make a Python release. Some steps are more + fuzzy than others because there's little that can be automated (e.g. + writing the NEWS entries). Where a step is usually performed by An + Expert, the role of that expert is given. Otherwise, assume the step is + done by the Release Manager (RM), the designated person performing the + release. The roles and their current experts are: - * RM = Release Manager: Benjamin Peterson <benjamin@python.org> (US/Central) + * RM = Release Manager: Georg Brandl <georg@python.org> (Central Europe) * WE = Windows: Martin von Loewis <martin@v.loewis.de> (Central Europe) * ME = Mac: Ronald Oussoren <ronaldoussoren@mac.com> (Central Europe) * DE = Docs: Georg Brandl <georg@python.org> (Central Europe) @@ -54,24 +53,21 @@ How to Make A Release following experts before updating the web pages and sending the announcement: WE, DE - XXX: We should include a dependency graph to illustrate the steps - that can be taken in parallel, or those that depend on other - steps. + XXX: We should include a dependency graph to illustrate the steps that can + be taken in parallel, or those that depend on other steps. As much as possible, the release steps are automated and guided by the - release script, which is available in the Python sandbox. The release - script is currently being maintained here: + release script, which is available in a separate repository: - http://svn.python.org/view/sandbox/trunk/release/ + http://hg.python.org/release/ We use the following conventions in the examples below. Where a release number is given, it is of the form X.YaZ, e.g. 2.6a3 for Python 2.6 alpha - 3, where "a" == alpha, "b" == beta, "rc" == release candidate. + 3, where "a" == alpha, "b" == beta, "rc" == release candidate. If a micro + release number is used, then we'll say X.Y.MaZ. - Final releases are named "releaseXY". The branch tag is "releaseXY-maint" - because this will point to the long lived maintenance branch. The fork - tag on the trunk is "releaseXY-fork". If a micro release number is used, - then we'll say X.Y.MaZ. + Release tags are named "vX.YaZ". The branch name for minor release + maintenance branches is "X.Y". This helps by performing several automatic editing steps, and guides you to perform some manual editing steps. @@ -81,18 +77,6 @@ How to Make A Release You probably need to coordinate with other people around the world. This IRC channel is where we've arranged to meet. - ___ Impose a check-in freeze by sending email to python-committers@python.org - - At this point, nobody except the RM or his duly assigned agents should - make any commits to the branches. The assigned agents are either from - the list above or by coordination as necessary. If a checkin needs to - be made, make sure to state in the checkin comment that the change was - approved. If the RM screwed up and some desperate last minute change to - the branch is necessary, it can mean extra work for others. So try to - avoid this! - - The RM has full authority to revert any unapproved commits. - ___ Check to see if there are any showstopper bugs. Go to http://bugs.python.org and look for any open bugs that can block @@ -127,19 +111,48 @@ How to Make A Release use your judgement, taking into account whether you are making an alpha, beta, or final release. - ___ Regenerate Lib/pydoc-topics.py + ___ Make a release clone. + + Create a local clone of the cpython repository (called the "release + clone" from now on). + + Also clone the repo at http://hg.python.org/cpython using the + server-side clone feature. The name of the new clone should preferably + have a "releasing/" prefix. The other experts will use the release + clone for making the binaries, so it is important that they have access + to it! + + Optionally, set up your local release clone to push to the remote + release clone by default (by editing .hg/hgrc to that effect). + + ___ Notify all committers by sending email to python-committers@python.org. + + Since we're now working with a distributed version control system, there + is no need to stop everyone from pushing to the main repo; you'll just + work in your own clone. Therefore, there won't be any checkin freezes. + + However, all committers should know the point at which your release + clone was made, as later commits won't make it into the release without + extra effort. + + ___ Make sure the current branch of your release clone is the branch you + want to release from. + + ___ Regenerate Lib/pydoc-topics.py. cd to the Doc directory and type ``make pydoc-topics``. Then copy ``build/pydoc-topics/pydoc-topics.py`` to ``../Lib/pydoc_topics.py``. - - ___ Check the docs for markup errors + + ___ Check the docs for markup errors. In the Doc directory, type ``make suspicious``. If any markup errors are found, fix them. + ___ Commit any changes to pydoc_topics.py and the doc sources. + ___ Bump version numbers via the release script. - .../sandbox/release/release.py --bump X.YaZ + $ .../release/release.py --bump X.YaZ This automates updating various release numbers, but you will have to modify a few files manually. If your $EDITOR environment variable is @@ -151,6 +164,8 @@ How to Make A Release content of this file. You should only need to review the text for sanity, and update the release date with today's date. + Commit the changes once you have reviewed them. + ___ Check the years on the copyright notice. If the last release was some time last year, add the current year to the copyright notice in several places: @@ -178,24 +193,22 @@ How to Make A Release alpha or beta releases. Note that Andrew Kuchling often takes care of this. - ___ If this is a final major release, branch the tree for X.Y + ___ Tag the release for X.YaZ. - When making a major release (e.g., for 2.6), you must create the - long-lived maintenance branch. To create a _branch_ (e.g., - release26-maint), do the following: + $ .../release/release.py --tag X.YaZ - .../sandbox/release/release.py --branch X.Y + ___ If this is a final major release, branch the tree for X.Y. - ___ If you just made the release branch, check out a clean version - into a new directory. You'll be doing the release from this new - branch. + When making a major release (e.g., for 3.2), you must create the + long-lived maintenance branch. + + ___ Note down the current revision ID of the tree. - % svn co \ - svn+ssh://pythondev@svn.python.org/python/branches/release26-maint + $ hg identify - ___ Set the original trunk up to be the next release. + ___ First, set the original trunk up to be the next release. - % .../sandbox/release/release.py --bump 2.7a0 + $ .../release/release.py --bump 3.3a0 ___ Edit all version references in the README @@ -205,27 +218,35 @@ How to Make A Release ___ The LICENSE file. Add the pending version to the list of releases, and be sure to check the release dates. - ___ There's a copy of the license in Doc/license.rst + ___ There's a copy of the license in Doc/license.rst. - ___ Doc/tutorial/interpreter.rst (2 references to '[Pp]ython26', one - to 'Python 2.6'). + ___ Doc/tutorial/interpreter.rst (2 references to '[Pp]ython32', one + to 'Python 3.2'). ___ Doc/tutorial/stdlib.rst and Doc/tutorial/stdlib2.rst, which have - each one reference to '[Pp]ython26'. + each one reference to '[Pp]ython32'. ___ Update the version number in configure.in and re-run autoconf. ___ Update the version numbers for the Windows builds in PC/ and - PCbuild/, which have references to python26. + PCbuild/, which have references to python32. - % find PC/ PCbuild/ \( -type f -and -not -wholename '*/.svn/*' \) | xargs sed -i 's/python26/python27/g' - % svn mv PC/os2emx/python26.def PC/os2emx/python27.def + $ find PC/ PCbuild/ -type f | xargs sed -i 's/python32/python33/g' + $ hg mv -f PC/os2emx/python32.def PC/os2emx/python33.def - ___ cd release26-maint # cd into the branch directory. + ___ Commit these changes to the default branch. + + ___ Now, go back to the previously noted revision and make the + maintenance branch *from there*. - ___ Tag the release for X.YaZ + $ hg update deadbeef # revision ID noted down before + $ hg branch 3.2 - .../sandbox/release/release.py --tag X.YaZ + ___ Push your commits to the remote release clone. + + $ hg push ssh://hg.python.org/releasing/... + + ___ Notify the experts that they can start building binaries. ___ STOP STOP STOP STOP STOP STOP STOP STOP @@ -233,9 +254,6 @@ How to Make A Release order to create the release. There are things you can do while you wait though, so keep reading until you hit the next STOP. - ___ Forward the commit message that created the tag to python-committers and - ask that the experts build the binaries. - ___ XXX The WE builds the Windows helpfile, using (in Doc/) either $ make htmlhelp (on Unix) @@ -244,64 +262,53 @@ How to Make A Release > make.bat htmlhelp (on Windows) - to create suitable input for HTML Help Workshop in - build/htmlhelp. HTML Help Workshop is then fired up on the - created python26.hhp file, finally resulting in an - python26.chm file. He then copies the file into the Doc + to create suitable input for HTML Help Workshop in build/htmlhelp. HTML + Help Workshop is then fired up on the created python26.hhp file, finally + resulting in an python26.chm file. He then copies the file into the Doc directories of the build trees (once for each target architecture). XXX The CHM file should also be scp'd to the docs download location. ___ XXX The WE then generates Windows installer files for each Windows - target architecture (for Python 2.6, this means x86 - and AMD64). He has one checkout tree per target architecture, - and builds the pcbuild.sln project for the appropriate - architecture. He then edits Tools/msi/config.py to update - full_current_version, sets snapshot to False and runs msi.py with - ActivePython 2.5 or Python 2.5 with pywin32. + target architecture (for Python 2.6, this means x86 and AMD64). He has + one checkout tree per target architecture, and builds the pcbuild.sln + project for the appropriate architecture. He then edits + Tools/msi/config.py to update full_current_version, sets snapshot to + False and runs msi.py with ActivePython 2.5 or Python 2.5 with pywin32. For that to work, the following prerequisites must be met: - PC\icons.mak must have been run with nmake. - - The cmd.exe window in which this is run must have Cygwin/bin - in its path (atleast for x86). + - The cmd.exe window in which this is run must have Cygwin/bin in its + path (atleast for x86). - The cmd.exe window must have MS compiler tools for the target - architecture in its path (VS 2003 for x86, the platform - SDK for AMD64). + architecture in its path (VS 2003 for x86, the platform SDK for + AMD64). - - The cmd.exe window must also have cabarc.exe from the CAB SDK - in its path. + - The cmd.exe window must also have cabarc.exe from the CAB SDK in its + path. - The WE checksums the files (*.msi and *.chm), uploads them to - some place in the net, and emails you the location and md5sums. + The WE checksums the files (*.msi and *.chm), uploads them to some place + in the net, and emails you the location and md5sums. - ___ Time to build the source tarball. If you created a branch, be - sure to cd to your working directory for the branch. E.g. + ___ Time to build the source tarball. Be sure to update your clone to the + correct branch. E.g. - % cd .../python26 + $ hg update 3.2 - ___ Do a "svn update ; svn status" in this directory. + ___ Do a "hg status" in this directory. You should not see any files. I.e. you better not have any uncommitted - changes in your working directory, but you may pick up some of the - expert's last minute changes. - - ___ If you've seen updates to existing files and you want these to make it - into the release, update the branches. - - ___ Delete the old tag branch and re-tag the tree - ___ Delete the maintenance branch and re-branch the trunk. - - This should be rare and indicates a breakdown in the process. + changes in your working directory. ___ Use the release script to create the source gzip and bz2 tarballs, md5 checksums, documentation tar and zip files, and gpg signature files. - .../sandbox/release/release.py --export X.YaZ + $ .../release/release.py --export X.YaZ - This will leave all the relevant files in a subdirectory called 'dist', - and the built docs in 'dist/docs'. + This will leave all the relevant files in a subdirectory called + 'X.YaZ/src', and the built docs in 'X.YaZ/docs' (for final releases). ___ scp or rsync all the files to your home directory on dinsdale.python.org. @@ -315,40 +322,40 @@ How to Make A Release virgin build passes the regression test. Here are the best steps to take: - % cd /tmp - % tar xzvf ~/Python-2.6c2.tgz # tar xjvf ~/Python-2.6c2.tar.bz2 - % cd Python-2.6c2 - % ls + $ cd /tmp + $ tar xvf ~/Python-3.2rc2.tgz + $ cd Python-3.2rc2 + $ ls (Do things look reasonable?) - % ls Lib + $ ls Lib (Are there stray .pyc files?) - % ls Doc/tools + $ ls Doc/tools (Make sure it doesn't contain "docutils", "sphinx", "jinja" or "pygments" directories. Also look for stray .pyc files.) - % ./configure + $ ./configure (Loads of configure output) - % make test + $ make test (Do all the expected tests pass?) If you're feeling lucky and have some time to kill, or if you are making a release candidate or final release, run the full test suite: - % make TESTOPTS='-u all' test + $ make TESTOPTS='-u all' test If the tests pass, then you can feel good that the tarball is fine. If some of the tests fail, or anything else about the freshly unpacked directory looks weird, you better stop now and figure out what the problem is. - ___ Now you need to go to dinsdale.python.org and move all the files - in place over there. Our policy is that every Python version gets its - own directory, but each directory may contain several releases. We keep - all old releases, moving them into a "prev" subdirectory when we have a - new release. + ___ Now you need to go to dinsdale.python.org and move all the files in + place over there. Our policy is that every Python version gets its own + directory, but each directory may contain several releases. We keep all + old releases, moving them into a "prev" subdirectory when we have a new + release. - So, there's a directory called "2.6" which contains Python-2.6a2.exe and - Python-2.6a2.tgz, along with a "prev" subdirectory containing - Python-2.6a1.msi, Python-2.6a1.tgz, Python-2.6a1.tar.bz2, etc. + So, there's a directory called "3.2" which contains Python-3.2.msi and + Python-3.2.tgz, along with a "prev" subdirectory containing + Python-3.2a1.msi, Python-3.2a1.tgz, Python-3.2a1.tar.bz2, etc. ___ On dinsdale, cd /data/ftp.python.org/pub/python/X.Y[.Z] creating it if necessary. @@ -395,9 +402,9 @@ How to Make A Release Make sure the md5 checksums match. Then unpack the tarball, and do a clean make test. - % make distclean - % ./configure - % make test + $ make distclean + $ ./configure + $ make test To ensure that the regression test suite passes. If not, you screwed up somewhere! @@ -499,65 +506,29 @@ How to Make A Release Now it's time to do some cleaning up. These steps are very important! - ___ If you made a non-maintenance branch, be sure to merge it into - the trunk! Now that we've released this branch, we don't need it any - more. We've already tagged it so we can always reproduce it. Note that - merging branches is a bit of a black art, but here's what's worked for - us. - - NOTE: If this was an X.Y major release, we will be using this as - the maintenance branch for a long time to come. - - ___ Check out a completely clean, virgin working directory of the - trunk, by doing this in the directory that is the parent of - your branch working directory python-XYaZ: - % svn co \ - svn+ssh://pythondev@svn.python.org/python/trunk python-clean - - ___ Run a diff against your branch by doing this in the common - parent directory containing both python-clean and python-XYaZ: - % diff -r python-clean python-26a2 | grep ^diff | grep -v /.svn/ \ - > /tmp/diffcmd.sh - - ___ Edit diffcmd.sh to get rid of files that you know don't have - important changes. You're looking for files that have updates - in the branch that haven't made it to the trunk. - - Generally you can ignore any changes to the Doc or Mac - subdirectories, or any changes to Windows related files. The - sub-RMs for those parts will take care of any necessary merges - from the branch to the trunk. - - If you've been diligent about merging changes from the trunk - into the branch, there shouldn't be many of these files. - - ___ Edit /tmp/diffcmd.sh, changing all the -r's into -u's. Run - the /tmp/diffcmd.sh command like so: - % sh /tmp/diffcmd.sh > /tmp/pydiff.txt - - ___ Attempt to patch your python-clean working directory. Do this - first, noting that --dry-run does not actually apply any - patches, it just makes sure that the patch command runs - successfully to completion: - % patch -p1 --dry-run < /tmp/pydiff.txt - - ___ If this goes well, run it again, taking out the --dry-run - option. If this fails, or if it prompts you for a file to - patch, try using -p0 instead of -p1. Otherwise, your diff - command was messed up, so try again. - - ___ cd to python-clean and do a "svn commit". Use as your log - message something like "Merging the rXYaZ-maint tag back into - the trunk". - ___ Do the guided post-release steps with the release script. - .../sandbox/release/release.py --done X.YaZ + $ .../release/release.py --done X.YaZ Review and commit these changes. - ___ Send email to python-committers informing them that the branch has been - unfrozen. + ___ Merge your release clone into the main development repo: + + $ cd ../cpython # your clone of the main repo + $ hg pull ssh://hg.python.org/cpython # update from remote first + $ hg pull ../cpython-releaseX.Y # now pull from release clone + + Now merge your release clone's changes in every branch you touched + (usually only one, except if you made a new maintenance release). + Easily resolvable conflicts may appear in Misc/NEWS. + + Commit and push to the main repo. + + ___ You can delete the remote release clone, or simply reuse it for the next + release. + + ___ Send email to python-committers informing them that the release has been + published. ___ Update any release PEPs (e.g. 361) with the release dates.