zest.releaser 2.9.3

Scripts to help with releasing software with Zest's conventions

Package releasing made easy

zest.releaser is collection of command-line programs to help you automate the task of releasing a software project. It’s particularly helpful with Python package projects, but it can also be used for non-Python projects. For example, it’s used to tag buildouts - a project only needs a version.txt file to be used with zest.releaser.

It will help you to automate:

• Updating the version number. The version number can either be in setup.py or version.txt. For example, 0.3 dev (current) to 0.3 (release) to 0.4 dev (new development version).

• Updating the history/changes file. It logs the release date on release and adds a new section for the upcoming changes (new development version).

• Tagging the release. It creates a tag in your version control system named after the released version number.

• Uploading a source release to PyPI. It will only do this if the package is already registered there, the Zest Releaser is careful not to publish your private projects! It can also check out the tag in a temporary directory in case you need to modify it.

Installation

Just a simple easy_install zest.releaser is enough.

Alternatively, buildout users can install zest.releaser as part of a specific project’s buildout, by having a buildout configuration such as:

[buildout]
parts = releaser

[releaser]
recipe = zc.recipe.egg
eggs = zest.releaser

You must also have a version control system installed. Zest.releaser currently supports Subversion and Mercurial (and others could be added).

Running

Zest.releaser gives you four commands to help in releasing python packages. They must be run in a version controlled checkout. The commands are:

• prerelease: asks the user for a version number (defaults to the current version minus a ‘dev’ or so), updates the setup.py or version.txt and the HISTORY.txt/CHANGES.txt/CHANGES with this and offers to commit those changes to subversion.

• release: copies the the trunk or branch of the current checkout and creates a version control tag of it. Makes a checkout of the tag in a temporary directory. Offers to register and upload a source dist of this package to PyPI (Python Package Index). Note: if the package has not been registered yet, it will not do that for you. You must register the package manually (python setup.py register) so this remains a conscious decision. The main reason is that you want to avoid having to say: “Oops, I uploaded our client code to the internet; and this is the initial version with the plaintext root passwords.”

• postrelease: asks the user for a version number (gives a sane default), adds a development marker to it, updates the setup.py or version.txt and the HISTORY.txt with this and offers to commit those changes to version control.

• fullrelease: all of the above in order.

There are two additional tools:

• longtest: small tool that renders a setup.py’s long description and opens it in a web browser. This assumes an installed docutils (as it needs rst2html.py).

• lasttagdiff: small tool that shows the diff of the currently committed trunk with the last released tag. Handy for checking whether all the changes are adequately described in the HISTORY.txt/CHANGES.txt.

Current assumptions

Zest.releaser originated at Zest software so there are some assumptions build-in that might or might not fit you. Lots of people are using it in various companies and open source projects, so it’ll probably fit :-)

• If you are using svn, your svn is structured with /trunk, /tags and optionally /branches. Both a /trunk or a /branches/something checkout is ok.

• There’s a version.txt or setup.py in your project. The version.txt has a single line with the version number (newline optional). The setup.py should have a single version = '0.3' line somewhere. You can also have it in the actual setup() call, on its own line still, as `` version = ‘0.3’,``. Indentation and the comma are preserved. If you need something special, you can always do a version=version and put the actual version statement in a zest.releaser-friendly format near the top of the file. Reading (in Plone products) a version.txt into setup.py works great, too.

• The history file (either HISTORY.txt or CHANGES.txt) restriction is probably the most severe at the moment. zest.releaser searches for a restructuredtext header with parenthesis. So something like:

  Changelog for xyz
  =================
  
  0.3 (unreleased)
  ----------------
  
  - Did something
  
  0.2 (1972-12-25)
  ----------------
  
  - Reinout was born.

  That’s just the style we started with. Pretty clear and useful. It also supports the current zopeskel style with 0.3 - unreleased.

Notes

Note that there are alternative release scripts available, for instance http://pypi.python.org/pypi/collective.releaser which installs itself as a setuptools command (“python setup.py release”), so it “only” works with setuptools projects.

The svn source can be found at https://svn.plone.org/svn/collective/zest.releaser/trunk .

Uploading to pypi server(s)

Like noted earlier, for safety reasons zest.releaser will only offer to upload your package to http://pypi.python.org when the package is already registered there. If this is not the case yet, you can go to the directory where zest.releaser put the checkout (or make a fresh checkout yourself. Then with the python version of your choice do:

python setup.py register sdist upload

For this to work you will need a .pypirc file in your home directory that has your pypi login credentials like this:

[server-login]
username:maurits
password:secret

Since python 2.6, or in earlier python versions with collective.dist, you can specify multiple indexes for uploading your package in .pypirc:

[distutils]
index-servers =
  pypi
  local

[pypi]
#pypi.python.org
username:maurits
password:secret

[local]
repository:http://localhost:8080/test/products/
username:maurits
password:secret
# You may need to specify the realm, which is the domain the
# server sends back when you do a challenge:
#realm:Zope

See http://pypi.python.org/pypi/collective.dist for more info.

When all this is configured correctly, zest.releaser will first reregister and upload at the official pypi (if the package is registered there already). Then it will offer to upload to the other index servers that you have specified in .pypirc.

To do

• Add hg support for lasttagdiff.

• Add support for bazaar.

• Add support for git.

Credits

• Reinout van Rees (The Health Agency) is the originator and main author.

• Maurits van Rees (Zest Software) added a heapload of improvements.

• Kevin Teague (Canada’s Michael Smith Genome Sciences Center) added support for multiple version control systems, most notable Mercurial.

• Wouter vanden Hove (University of Gent) added support for uploading to multiple servers, using collective.dist.

Changelog for zest.releaser

2.9.3 (2009-09-22)

• Uploading to multiple package indexes should now work in python2.6 (though ironically it now does not work for me on python2.4, but that has nothing to do with zest.releaser.) Added documentation for this. [maurits]

• Make sure the next version suggestion for 1.0rc6 is 1.0rc7. [maurits]

• In subversion, first try to get the package from the setup.py before falling back to the svn info, just like for mercurial. This fixes the problem that e.g. Products.feedfeeder was not recognized as being on pypi as the svn directory name was feedfeeder. [maurits]

2.9.2 (2009-09-17)

• Ümläüts in a changelog don’t break the logger anymore when using python2.6.2 when the umlauts turn up in the diff. This is due to a 2.6.2 regression bug, see http://bugs.python.org/issue5170. Should be fixed in 2.6.3 when it comes out. [reinout]

• (Release 2.9 and 2.9.1 are unreleased because of a setuptools bug with, sigh, non-ascii characters which made a dirty setup.py hack necessary). [reinout]

2.8 (2009-08-27)

• Fixed the release command when used in a french environment. In French “svn info” returns ‘URL :’, not ‘URL:’. [vincentfretin]

2.7 (2009-07-08)

• Before asking setup.py for its version or name, first run egg_info, as that may get rid of some warnings that otherwise end up in the extracted version or name, like UserWarnings. [maurits]

2.6 (2009-05-25)

• Small change: the questions don’t print a newline anymore after the question (and before the user pressed enter). This makes it clearer if enter has been pressed yet. Suggestion by jkolman. [reinout]

2.5 (2009-05-20)

• Revert to previous behaviour: when a package has not been released yet on pypi, decline to register it: the first time should be deliberate and manual, to avoid accidentally uploading client packages to pypi. [maurits]

2.4 (2009-05-15)

• Factored release.py out into a new pypi.py, solving a few possible problems with missing or misconfigured .pypirc files. [maurits]

2.3 (2009-05-11)

• Fixed release script when the .pypirc file does not contain a distutils section or that section does not contain a index-servers option. [maurits]

2.2 (2009-05-11)

• postrelease: suggestion for next version after 1.1.19 is not 1.1.110, but 1.1.20. [maurits]

• Make it work with collective.dist (mregister/mupload) [WouterVH] see http://plone.org/documentation/tutorial/how-to-upload-your-package-to-plone.org/installing-collective.dist

2.1 (2009-04-09)

• Fix lasttagdiff command to work with Mercurial by truncating the ‘+’ character from the revision id, since that only indicates uncommitted changes exist.

• Make sure we find package/name/HISTORY.txt before we find docs/HISTORY.txt. [maurits]

• Fixed checking for self.internal_filename: we would incorrectly check (‘.’, ‘s’, ‘v’, ‘n’) instead of ‘.svn’. [maurits]

2.0 (2009-04-01)

• Added tag_url method to get lasttagdiff (and zest.stabilizer) working again. [maurits]

• Merged kteague-multi-vcs branch with, woohoo, mercurial support! [reinout]

• Mercurial support by Kevin Teague. [kteague]

• postrelease put a space in the new version number in setup.py (between version number and dev). Removed this space as it is not necessary (in best case). [icemac]

1.13 (2009-03-17)

• Also looking for CHANGES in addition to HISTORY.txt and CHANGES.txt as some packages use that convention. [reinout]

• Added lasttagdiff command that shows the diff between the last release and the currently committed trunk. Handy for checking whether the changelog is up to date. [reinout]

1.12 (2009-03-17)

• When doing a fullrelease and if the release step made a checkout of the tag into an temp directory, that temp directory is again printed after fullrelease finishes. Otherwise you’ve got to do a lot of scrolling. [reinout]

1.11 (2009-03-04)

• When the found history file contains no version headings, look for a second history file: more than once I have the standard docs/HISTORY.txt that paster creates and I just add a pointer there to the real package/name/HISTORY.txt. [maurits]

1.10 (2009-02-25)

• A `` version = ‘1.0’,`` in setup.py is now also rewritten correctly. Previously just a version = '1.0' would be injected, so without indentation and comma. [reinout]

• Ask before checking out the tag. Sometimes the checkout is huge and you know you don’t want it. You don’t get asked for a pypi upload, though if you don’t check out the tag. [reinout]

1.9 (2009-02-24)

• ‘release’ now also makes a tag checkout in a temporary directory. [Reinout]

• Made ‘longtest’ work on Linux as there the command is ‘rst2html’ and apparently on the Mac it is ‘rst2html.py’. [maurits]

1.8 (2009-02-23)

• Added ‘longtest’ command that renders a setup.py’s long description and opens it in a web browser. [reinout]

1.7 (2009-02-16)

• Supporting alternative history version header format: ‘version - date’. [reinout]

1.6 (2009-02-14)

• Patch by Michael Howitz: sys.executable is used instead of a string that doesn’t work on every system. [reinout]

1.5 (2009-02-11)

• Changed y/n into Y/n, so defaulting to ‘yes’. [reinout]

• Improved the documentation. [reinout]

• When a yes/no question is asked, do not treat ‘no’ as the default but explicitly ask for an input – it was too easy to press enter and wrongly expect ‘yes’ as default. [maurits]

1.4 (2008-10-23)

• Fixed missing import of utils. [maurits]

1.3 (2008-10-23)

• Moved stabilize script to zest.stabilizer so that zest.releaser is just for releasing individual packages. Nice, tidy, reusable. [reinout]

• Allowing ‘-v’ option on all commands: it gives you debug-level logging. [reinout]

1.2 (2008-10-16)

• We now prefer the version from setup.py over any version.txt file found. When getting or changing the version we get/change the setup.py version when it differs from the found version.txt version. [maurits]

1.1 (2008-10-15)

• Cleaned out zest-specific stuff. Cleaned up ‘release’. [reinout]

1.0 (2008-10-15)

• Stabilize looks up the most recent tag of our development packages and uses gp.svndevelop to allow svn checkouts as development eggs. [reinout]

• Do not look for version.txt in directories that are not handled by subversion. Use case: Products.feedfeeder, which has a buildout.cfg and so can have a parts directory with lots of version.txt files… [maurits]

0.9 (2008-10-02)

• release: offer to register and upload the egg to the cheese shop. After that you still have the option to upload to our own tgz server. [maurits]

• postrelease: for the suggestion of a new version simply try add 1 to the last character in the version; the previous logic failed for example for ‘1.0b3’. [maurits]

• prerelease: ask user to enter next version (give him a suggestion). Handy when you want to change ‘1.0b3 dev’ into ‘1.0’. [maurits]

• Started ‘stabilize’. [reinout]

0.8 (2008-09-26)

• fullrelease: change back to the original directory after each pre/actual/post release step. [maurits]

• release: switch back to original directory when ready to fix ‘commit to tag’ error. [maurits]

• prerelease: quit when no version is found. [maurits]

• Reverted sleeping fix from 0.7 as it did not work. [maurits]

0.7 (2008-09-26)

• fullrelease: hopefully fix a ‘commit on tag’ bug by sleeping three seconds before doing the post release. [maurits]

0.6 (2008-09-26)

• Added fullrelease script that does a prerelease, actual release and post release in one go. [maurits]

0.5 (2008-09-26)

• Factored part of prerelease.check_version() out into utils.cleanup_version(). We now use that while setting the version in the history during postrelease. [maurits]

• Add newline at the end of the generated version.txt. [maurits]

0.4 (2008-09-26)

• Made the logging userfriendly.

0.3 (2008-09-26)

• Postrelease: Better injection of history. Various other robustness fixes.

0.2 (2008-09-26)

• postrelease: added suggestion for new version (a plain enter is enough to accept it). [reinout]

• prerelease: ask before changing version + solidified regex for heading detection. [reinout]

• prerelease: detect non-development versions better and change them. [maurits]

• prerelease: made the commit message read: ‘Preparing release xxx’. [maurits]

• postrelease: made the new version something like ‘1.0 dev’. [maurits]

• postrelease: we now add some lines to the history now. [maurits]

• prerelease: try changing the version to a non-development version, stripping off something like ‘(…)’. [maurits]

• release: Refactored so release.py has the ‘main’ function required by setup.py. [maurits]

0.1 (2008-09-24)

• Got a basic version of the prerelease script working (version check, history file updating, committing). [reinout]

• Started by copying the guidelines script. [reinout]