zest.releaser 3.6

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, Mercurial and Git (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 you 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 new version number and offers to commit those changes to subversion (or bzr or hg or git)

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

• If using Python 2.4 you don’t want to have tar.gz eggs due to an obscure bug on python

Development notes, bug tracker

The svn source can be found at https://svn.plone.org/svn/collective/zest.releaser/trunk . If you have access to the collective, you can fix bugs right away. Bigger changes on a branch please and mail reinout@vanrees.org and maurits@vanrees.org about it :-)

If you are going to do a fix or want to run the tests, please see the DEVELOPERS.txt file in the root of the package.

Bugs can be added to https://bugs.launchpad.net/zest.releaser .

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.

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.

Entry point specification

An entry point is configured like this in your setup.py:

entry_points={
    #'console_scripts': [
    #    'myscript = my.package.scripts:main'],
    'zest.releaser.prereleaser.middle': [
        'dosomething = my.package.some:some_entrypoint,
        ]},

Replace prereleaser and middle in zest.releaser.prereleaser.middle with prerelease/release/postrelease and before/middle/after where needed.

You’ll have to make sure that the zest.releaser scripts know about your entry points, for instance by placing your egg (with entry point) in the same zc.recipe.egg section in your buildout as where you placed zest.releaser. Or, if you installed zest.releaser globally, your egg-with-entrypoint has to be globally installed, too.

Comments about data dict items

Your entry point gets a data dictionary: the items you get in that dictionary are documented below. Some comments about them:

• Not all items are available. If no history/changelog file is found, there won’t be any data['history_lines'] either.

• Items that are templates are normal python string templates. They use dictionary replacement: they’re actually passed the same data dict. For instance, prerelease’s data['commit_message'] is by default Preparing release %(new_version)s. A “middle” entry point could modify this template to get a different commit message.

Prerelease data dict items

commit_msg

Message template used when committing

history_file

Filename of history/changelog file (when found)

history_header

Header template used for 1st history header

history_lines

List with all history file lines (when found)

name

Name of the project being released

new_version

New version (so 1.0 instead of 1.0dev)

original_version

Version before prereleasing (e.g. 1.0dev)

today

Date string used in history header

workingdir

Original working directory

Release data dict items

name

Name of the project being released

tag_already_exists

Internal detail, don’t touch this :-)

tagdir

Directory where the tag checkout is placed (if a tag checkout has been made)

version

Version we’re releasing

workingdir

Original working directory

Postrelease data dict items

commit_msg

Message template used when committing

dev_version

New development version with dev marker (so 1.1dev)

dev_version_template

Template for dev version number

history_header

Header template used for 1st history header

name

Name of the project being released

new_version

New development version (so 1.1)

nothing_changed_yet

First line in new changelog section

workingdir

Original working directory

3.6 (2010-04-13)

• A version='1.0', string inside the setup() call no longer has non-pep8 spaces around the =. Fixes https://bugs.launchpad.net/zest.releaser/+bug/562122 [reinout]

• Got rid of ugly setup.py hack with UltraMagicString that was meant to avoid encoding errors when registering this package at pypi but which was not working for python2.4 (at least with collective.dist). Only ascii is allowed in the long_description if you want to avoid problems at one point or another. [maurits]

3.5 (2010-02-26)

• Treat CHANGES.txt and HISTORY.txt the same: the first that is found in a directory is chosen for changing, instead of first looking everywhere for a HISTORY.txt and then for a CHANGES.txt. [maurits]

3.4 (2010-02-02)

• Always build zip files if using python2.4 [do3cc]

• bugfix: added ‘spreaded_internal’ property to BaseVersionControl objects, so filefind() does not exclude a directory just because there is no ‘.git’ folder in it. It still excludes directory where there is no ‘.svn’ folder in SVN repositories. [vincent]

3.3 (2009-12-29)

• Fixed test failures when run on a computer with a new style pypi config. We now always use an old style config when running the tests. [maurits]

• Fixed the release command for hg 1.1 (e.g. Ubuntu 9.04). [maurits]

3.2 (2009-12-22)

• Replaced commands.getoutput() with a system() function grabbed from buildout on suggestion by Adam Groszer. Goal: make zest.releaser work also on windows.

• Improved entry point documentation.

• Added launchpad bugtracker at https://bugs.launchpad.net/zest.releaser (and pointing at that in the documentation).

3.1 (2009-11-27)

• Added documentation for entry points. [reinout]

3.0 (2009-11-27)

• Added support for extension by means of entry points. There is no documentation that advertises it yet as I want to treat it as experimental till I’ve used it a few times. [reinout]

2.12 (2009-11-26)

• Fixed mercurial sdist creation. [reinout]

• A missing history file does not result anymore in a keyerror in prerelease. [reinout]

• Added lots of test output normalization so that errors aren’t hidden by the large number of ... in the doctests. [reinout]

2.11 (2009-11-25)

• Added /tag besides /tags for subversion [gotcha]

• Fixed tests failures. [gotcha]

2.10 (2009-10-22)

• Added support for git. [reinout]

• Lots of internal refactoring and small fixes. [reinout]

• Started tests. zest.releaser went from 0 to 94% coverage. [reinout]

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)

• Umlauts 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]