zest.releaser 1.13

Scripts to help with releasing software with Zest's conventions

Zest release scripts

Summary: package releasing made easy

• Updates the version number. 0.3 dev (current) to 0.3 (release) to 0.4 dev (new development version). Either in setup.py or in version.txt.

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

• Tags the release in svn with the version number.

• Uploads a source release to pypi (if the package is available there). It also checks out the tag in a temporary directory in case you need to modify it.

Note that zest.releaser isn’t restricted to python packages. We use it regularly to tag buildouts. You only need a version.txt in your svn checkout.

Installation

Just a simple easy_install zest.releaser is enough.

It gives you four commands to help in releasing python packages. They must be run in a subversion checkout. These are the commands:

• 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 subversion 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 subversion.

• 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.

• 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 .

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

To do

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

Credits

• Reinout van Rees (Zest software) is the originator and main author.

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

Changelog for zest.releaser

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]