Media.readthedocs.org

zest.releaser Documentation
Release 3.51.dev0
Reinout and Maurits van Rees
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 . . . . . . . . . . . . . . . . . . . . . . . . . . 22 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 zest.releaser Documentation, Release 3.51.dev0
Make easy, quick and neat releases of your Python packages. You need to change the version number,add a new heading in your changelog, record the release date, svn/git/bzr/hg tag your project, perhapsupload it to pypi. zest.releaser takes care of the boring bits for you.
Here’s an overview of the documentation we have for you.
Contents
zest.releaser Documentation, Release 3.51.dev0
Contents
CHAPTER 1
Package releasing made easy: zest.releaser overview and
installation
zest.releaser is collection of command-line programs to help you automate the task of releasing a Pythonproject.
It does away with all the boring bits. This is what zest.releaser automates for you: The version number can either be in setup.py or version.txt (or in a __versions__ attribute in a Python file). For example, it switchesyou from 0.3.dev0 (current development version) to 0.3 (release) to 0.4.dev0 (new devel-opment version).
• It updates the history/changes file. It logs the release date on release and adds a new heading for the upcoming changes (new development version).
• It tags the release. It creates a tag in your version control system named after the released version • It optionally uploads a source release to PyPI. It will only do this if the package is already regis- tered there (else it will ask, defaulting to ‘no’); zest releaser is careful not to publish your privateprojects! 1.1 Most important URLs
• We’re so we’re only an pip install zest.releaser away from installation on And. we’re automatically being tested by Travis: 1.2 Installation
Just a simple pip install zest.releaser or easy_install zest.releaser is enough.
Alternatively, buildout users can install zest.releaser as part of a specific project’s buildout, by having abuildout configuration such as: zest.releaser Documentation, Release 3.51.dev0
1.3 Version control systems: svn, hg, git, bzr
Of course you must have a version control system installed. zest.releaser currently supports: Others could be added if there are volunteers! Git and mercurial support have been contributed yearsago when we were working with bzr and subversion, for instance.
1.4 Available commands
Zest.releaser gives you four commands to help in releasing python packages. They must be run in aversion 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 CHANGES/HISTORY/CHANGELOG file (with either.rst/.txt/.markdown or no extension) with this new version number and offers to commit thosechanges 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 sourcedist of this package to PyPI (Python Package Index). Note: if the package has not been registeredyet, it will not do that for you. You must register the package manually (python setup.pyregister) so this remains a conscious decision. The main reason is that you want to avoidhaving to say: “Oops, I uploaded our client code to the internet; and this is the initial version withthe 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 CHANGES/HISTORY/CHANGELOG file withthis and offers to commit those changes to version control. Note that with git and hg, you’d alsobe asked to push your changes (since 3.27). Otherwise the release and tag only live in your localhg/git repository and not on the server.
• fullrelease: all of the above in order.
• 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).
Chapter 1. Package releasing made easy: zest.releaser overview and installation
zest.releaser Documentation, Release 3.51.dev0
• 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 changes file.
1.4. Available commands
zest.releaser Documentation, Release 3.51.dev0
Chapter 1. Package releasing made easy: zest.releaser overview and installation
CHAPTER 2
Version handling
2.1 Where does the version come from?
A version number is essentially what zest.releaser cannot do without. A version number can come fromthree different locations: • The setup.py file. Two styles are supported: • If no setup.py is found, zest.releaser looks for a version.txt file. It should contain just a version number (a newline at the end is OK).
Originally the version.txt was only meant to support really old and ancient packages,but it turned out to be quite useful for non-Python packages, too. A completely static website, forinstance, that you do want to release and that you do want a changelog for.
• A __version__ attribute in a Python file.
You need to tell zest.releaser which Python file by adding (or updating) the setup.cfg file next to the setup.py.
[zest.releaser] header and a python-file-with-version option: python-file-with-version = mypackage/__init__.py Because you need to configure this explicitly, this option takes precedence over any setup.pyor version.txt file.
2.2 Where is the version number being set?
Of those three locations where the version can come from, only the first one found is also set to the newvalue again. Zest.releaser assumes that there’s only one location.
zest.releaser Documentation, Release 3.51.dev0
the version should have one source and all the others should be derived from it.
2.3 Using the version number in setup.py and as __version__
Here are opinionated suggestions from the zest.releaser main authors about how to use the version in-formation. For some other ideas, see the discussion.
• The version in the setup.py is the real version.
• Add a __version__ attribute in your main module. Often this will be an __init__.py. Set this version attribute with pkg_resources, which is automatically installed as part of setup-tools/distribute. Here’s from zest/releaser/__init__.py: import pkg_resources
__version__ = pkg_resources.get_distribution("zest.releaser").version >>> import zest.releaser
>>> zest.releaser.__version__
• If you use for generating your documentation, use the same pkg_resources trick to set the version and release in your Sphinx’s conf.py. See Chapter 2. Version handling
CHAPTER 3
Uploading to pypi (or custom servers)
When the (full)release command tries to upload your package to a pypi server, zest.releaser basically justexecutes the command python setup.py register sdist --formats=zip upload.
For safety reasons zest.releaser will only offer to upload your package to when thepackage is already registered there. If this is not the case yet, you get a confirmation question whetheryou want to create a new package.
If the setup.py register . command fails, you probably need to configure your PyPI config-uration file. And of course you need to have setuptools/distribute installed.
3.1 PyPI configuration file (~/.pypirc)
For uploads to PyPI to work you will need a .pypirc file in your home directory that has your pypilogin credentials, like this: 3.2 Uploading to other servers
Since python 2.6 (or in earlier python versions, with collective.dist) you can specify multiple indexes foruploading your package in your .pypirc: repository:http://localhost:8080/test/products/ # You may need to specify the realm, which is the domain the zest.releaser Documentation, Release 3.51.dev0
# server sends back when you do a challenge: When all this is configured correctly, zest.releaser will first register and upload at the official pypi (if thepackage is registered there already). Then it will offer to upload to the other index servers that you havespecified in .pypirc.
Note that since version 3.15, zest.releaser also looks for this information in the setup.cfg if your packagehas that file. One way to use this, is to restrict the servers that zest.releaser will ask you upload to. Ifyou have defined 40 index-servers in your pypirc but you have the following in your setup.cfg, you willnot be asked to upload to any server: Note that after creating the tag we still ask you if you want to checkout that tag for tweaks orpypi/distutils server upload. We could add some extra checks to see if that is really needed, butsomeone who does not have index-servers listed, may still want to use an entry point like to do uploading, or do some manual steps first before uploading.
Some people will hardly ever want to do a release on PyPI but in 99 out of 100 cases only want to createa tag. They won’t like the default answer of ‘yes’ to that question of whether to create a checkout ofthe tag. So since version 3.16 you can influence this default answer. You can add some lines to the.pypirc file in your home directory to change the default answer for all packages, or change it forindividual packages in their setup.cfg file. The lines are this: You can use no/false/off/0 or yes/true/on/1 as answers; upper, lower or mixed case are all fine.
3.3 Including all files in your release
By default, only the Python files and a README.txt are included (by setuptools) when you make arelease. So you miss out on your changelog, json files, stylesheets and so on. There are two strategies toinclude those other files: • Add a MANIFEST.in file in the same directory as your setup.py that lists the files you want to include. Don’t worry, wildcards are allowed. Actually, zest.releaser will suggest a sampleMANIFEST.in for you if you don’t already have it. The default is often good enough.
• Setuptools can detect which files are included in your version control system (svn, git, etc.) which The last approch has a problem: not every version control system is supported out of the box. So youmight need to install extra packages to get it to work. So: use a MANIFEST.in file to spare you thetrouble. If not, here are some extra packages: • setuptools-git (Setuptools plugin for finding files under Git version control) • setuptools_hg (Setuptools plugin for finding files under Mercurial version control) • setuptools_bzr (Setuptools plugin for finding files under Bazaar version control) • collective.dist (when using python2.4, depending on your ~/.pypirc file) Chapter 3. Uploading to pypi (or custom servers)
zest.releaser Documentation, Release 3.51.dev0
• setuptools_subversion (Setuptools plugin for finding files under Subversion version control.) You probably need this when you upgrade to the recent subversion 1.7. If you suddenly start miss-ing files in the sdists you upload to PyPI you definitely need it. Alternatively: set up a properMANIFEST.in as that method works with any version control system.
In general, if you are missing files in the uploaded package, the best is to put a proper MANIFEST.infile next to your setup.py. See for an example.
3.4 Running automatically without input
Sometimes you want to run zest.releaser without hitting <enter> all the time. You might want to runzest.releaser from your automatic test environment, for instance. For that, there’s the --no-inputcommandline option. Pass that and all defaults will be accepted automatically.
This means your version number and so must be OK. If you want to have a different version numberfrom the one in your setup.py, you’ll need to change it yourself by hand. And the next versionnumber will be chosen automatically, too. So 1.2 will become 1.3. This won’t detect that you mightwant to do a 1.3 after a 1.2.1 bugfix release, but we cannot perform feats of magic in zest.releaser :-) In case you always want to accept the defaults, a setting in your setup.cfg is available: An important reminder: if you want to make sure you never upload anything automatically to the pythonpackage index, include the release = no setting in setup.cfg: 3.4. Running automatically without input
zest.releaser Documentation, Release 3.51.dev0
Chapter 3. Uploading to pypi (or custom servers)
CHAPTER 4
Assumptions
Zest.releaser originated at so there are some assumptions build-in that might or might notfit 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 (or /tag) and optionally /branches (or /branch). Both a /trunk or a /branches/something checkout is ok.
• We absolutely need a version. 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.pyshould have a single version = ’0.3’ line somewhere. You can also have it in the actualsetup() call, on its own line still, as ‘‘ version = ‘0.3’,‘‘. Indentation and the comma arepreserved. If you need something special, you can always do a version=version and putthe actual version statement in a zest.releaser-friendly format near the top of the file. Reading (inPlone products) a version.txt into setup.py works great, too.
• The history/changes file restriction is probably the most severe at the moment. zest.releaser searches for a restructuredtext header with parenthesis. So something like: That’s just the style we started with. Pretty clear and useful.
zest.releaser Documentation, Release 3.51.dev0
Chapter 4. Assumptions
CHAPTER 5
Further reading
Mighty fine documementation, the stuff you’re reading now. But some other suggestions, ideas anda different tone might help you improve your package releasing. So here are some pointers to othermaterial.
Don’t forget to look at the comments.
Photo of Reinout introducing zest.releaser at the 2010 Djangocon.eu in Berlin.
Note: If you have something nice to add here, mail and/or And documentation on zest.releaser as a project; for instance for reporting bugs and fixing the code: zest.releaser Documentation, Release 3.51.dev0
Chapter 5. Further reading
CHAPTER 6
Improving zest.releaser: report bugs, fork on github or email us
Did you find a bug? Do you have an improvement? Do you have questions? We run zest.releaser as aproper open source project on github at so you have threebasic options: • Feel free to report bugs on And feature requests, too. Normally you’ll get a quick reply within a day or so, depending on our relative timezones. If you don’t get an answerwithin a few days, please send off a quick email to remind us.
• Hey, we’re on github, so fork away to your heart’s delight. We got a couple of nice fixes and If you are going to fork zest.releaser, take a look at forsetup and test running information.
• Email Reinout and Maurits at and Please email us both at the same time, this way at least one of us can give you a quick reply.
zest.releaser Documentation, Release 3.51.dev0
Chapter 6. Improving zest.releaser: report bugs, fork on github or email us
CHAPTER 7
• (Nelen & Schuurmans) is the originator and main author.
• (Zest Software) added a heapload of improvements.
• (Canada’s Michael Smith Genome Sciences Center) added support for multiple version control systems, most notable Mercurial.
• (University of Gent) added support for uploading to multiple servers, using • (BubbleNet) added /tag besides /tags for subversion.
zest.releaser Documentation, Release 3.51.dev0
Chapter 7. Credits
CHAPTER 8
Information for developers of zest.releaser
8.1 Running tests
We like to use zc.buildout to get a test environment with any versions of needed python packages pinned.
When you are in the root folder of your zest.releaser checkout, do this: 8.2 Python versions
The tests currently pass on python 2.6 and 2.7. Using 2.6.2 specifically will give test failures. Traviscontinuous integration tests 2.6 and 2.7 for us automatically.
8.3 Necessary programs
To run the tests, you need to have the supported versioning systems installed: svn, hg (mercurial), gitand git-svn. On ubuntu: $ sudo apt-get install subversion git bzr mercurial git-svn There may be test failures when you have different versions of these programs. In that case, pleaseinvestigate as these may be genuine errors.
8.4 Setuptools is needed
You also need distribute (or setuptools) in your system path.
‘sys.executable setup.py egg_info’ directly (in the tests and in the actual code), which will give animport error on setuptools otherwise. There is a branch with a hack that solves this but it sounds toohacky.
zest.releaser Documentation, Release 3.51.dev0
8.5 Configuration for mercurial, bzr and git
For mercurial you may get test failures because of extra output like this: No username found, using ’name@domain’ instead.
To avoid this, create a file ~/.hgrc with something like this in it: username = Author Name <email@address.domain> If you keep having problems, quite good.
There is a similar problem with bazaar. Since bzr version 2.2, it refuses to guess what your usernameand email is, so you have to set it once, like this, otherwise you get test failures: $ bzr whoami "Author Name <email@address.domain>" $ git config --global user.name "Your Name" $ git config --global user.email you@example.com For release testing we expected a functioning .pypirc file in your home dir, with an old-style configura-tion, but the tests now use an own config file.
Chapter 8. Information for developers of zest.releaser
CHAPTER 9
Entrypoints: extending/changing zest.releaser
A zest.releaser entrypoint gets passed a data dictionary and that’s about it. You can do tasks like gener-ating documentation. Or downloading external files you don’t want to store in your repository but thatyou do want to have included in your egg.
Every release step (prerelease, release and postrelease) has three points where you can hook in an entrypoint: before Only the workingdir and name are available in the data dictionary, nothing has happened middle All data dictionary items are available and some questions (like new version number) have been asked. No filesystem changes have been made yet.
after The action has happened, everything has been written to disk or uploaded to pypi or whatever.
For the release step it made sense to create one extra entry point: after_checkout The middle entry point has been handled, the tag has been made, a checkout of that tag has been made and we are now in that checkout directory. Of course, when the user chooses notto do a checkout, this entry point never triggers.
Note that an entry point can be specific for one package (usually the package that you are now releasing)or generic for all packages. An example of a generic one is whichoffers to upload the generated distribution to a chosen destination (like a server for internal companyuse). If your entry point is specific for the current package only, you should add an extra check to makesure it is not run while releasing other packages; something like this should do the trick: def my_entry_point(data):
if data[’name’] != ’my.package’:
9.1 Entry point specification
An entry point is configured like this in your setup.py: ’myscript = my.package.scripts:main’], ’zest.releaser.prereleaser.middle’: [ ’dosomething = my.package.some:some_entrypoint’, zest.releaser Documentation, Release 3.51.dev0
Replace prereleaser and middle in zest.releaser.prereleaser.middle with prere-lease/release/postrelease and before/middle/after where needed.
See the setup.py of zest.releaser itself for some real world examples.
You’ll have to make sure that the zest.releaser scripts know about your entry points, for instance by plac-ing your egg (with entry point) in the same zc.recipe.egg section in your buildout as where you placedzest.releaser. Or, if you installed zest.releaser globally, your egg-with-entrypoint has to be globallyinstalled, too.
9.2 Comments about data dict items
Your entry point gets a data dictionary: the items you get in that dictionary are documented below. Somecomments about them: If no history/changelog file is found, there won’t be any • Items that are templates are normal python string templates.
they’re actually passed the same data dict.
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.
9.3 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) new_version New version (so 1.0 instead of 1.0dev) original_version Version before prereleasing (e.g. 1.0dev) 9.4 Release data dict items
tag_already_exists Internal detail, don’t touch this :-) tagdir Directory where the tag checkout is placed (if a tag checkout has been made) Chapter 9. Entrypoints: extending/changing zest.releaser
zest.releaser Documentation, Release 3.51.dev0
9.5 Postrelease data dict items
commit_msg Message template used when committing dev_version New development version with dev marker (so 1.1.dev0) dev_version_template Template for dev version number history_header Header template used for 1st history header new_version New development version (so 1.1) nothing_changed_yet First line in new changelog section 9.5. Postrelease data dict items
zest.releaser Documentation, Release 3.51.dev0
Chapter 9. Entrypoints: extending/changing zest.releaser
CHAPTER 10
Changelog for zest.releaser
10.1 3.51 (unreleased)
10.2 3.50 (2014-01-16)
• Changed command “hg manifest” to “hg locate” to list files in Mercurial. The former prints out file permissions along with the file name, causing a bug. [rafaelbco] 10.3 3.49 (2013-12-06)
• Support git-svn checkouts with the default “origin/” prefix. [kuno] 10.4 3.48 (2013-11-26)
• When using git, checkout submodules. [dnozay] 10.5 3.47 (2013-09-25)
• Always create an egg (sdist), even when there is no proper pypi configuration file. This helps plugins that use our entry points. Fixes [maurits] 10.6 3.46 (2013-06-28)
• Support actually updating VERSION as well. Issue #43.
zest.releaser Documentation, Release 3.51.dev0
10.7 3.45 (2013-04-17)
• Supporting VERSION (without extension) in addition to the old-zope-products-VERSION.txt 10.8 3.44 (2013-03-21)
• Added optional python-file-with-version setting for the [zest.releaser] section in setup.cfg. If set, zest.releaser extracts the version from that file’s __version__ attribute.
(See • File writes now use the platform’s default line endings instead of always writing \n unix style line endings. (Technically, we write using w instead of wb mode).
• Added link to other documentation sources in the sphinx docs.
• Noting in our pypi classifiers that we support python 2.6+, not python 2.4/2.5. Slowly things will creep into zest.releaser’s code that break compatibility with those old versions. And we want toget it to work on python 3 and that’s easier with just 2.6/2.7 support.
10.9 3.43 (2013-02-04)
• Added --no-input commandline option for running automatically without asking for in- Useful when started from some build tool.
10.10 3.42 (2013-01-07)
• When finding multiple version, changes or history files, pick the one with the shortest path. [mau- • Support project-specific hooks listed in setup.cfg. [iguananaut] 10.11 3.41 (2012-11-02)
• Getting the version from setup.py can give a traceback if the setup.py has an error. During prere- lease this would result in a proposed version of ‘Traceback’. Now we print the traceback and quit.
[maurits] 10.12 3.40 (2012-10-13)
• Support svn (1.7+) checkouts that are not directly in the root. Only applies when someone checks out a whole tree and wants to release one of the items in a subdirectory. Fixes #27.
Chapter 10. Changelog for zest.releaser
zest.releaser Documentation, Release 3.51.dev0
10.13 3.39 (2012-09-26)
• Only search for files in version control. This is when finding a history file or version.txt file. We should not edit files that are not in our package. Fixes issue #22. [maurits] 10.14 3.38 (2012-09-25)
• Fixed svn tag extraction on windows: a \r could end up at the end of every tag name. Thanks • Small fixes to the developers documentation and to the automatic tests configuration.
10.15 3.37 (2012-07-14)
• Documentation update! Started sphinx documentation at Removed documentation from the README and put it into sphinx.
• Actually ask if the user wants to continue with the release when there is no MANIFEST.in. We asked for a yes/no answer, but the question was missing. [maurits] 10.16 3.36 (2012-06-26)
• Improved changes/history file detection and fixed the documentation at this point. We now recog- nize CHANGES, HISTORY and CHANGELOG with .rst, .txt, .markdown and with no extension.
• Set up integration. Our tests pass on python 2.5, 2.6 and 2.7.
10.17 3.35 (2012-06-21)
• When checking for recommended files, ask if the user wants to continue when we suspect the created PyPI release may be broken. See issue #10. [maurits] 10.18 3.34 (2012-03-20)
• In the warning about a missing MANIFEST.in file, tools_subversion/git, etc. Fixes issue #4. [maurits] 10.19 3.33 (2012-03-20)
• Fix python 2.4 issues with tarfile by always creating a zip file. Formerly we would only do this when using python2.4 for doing the release, but a tarball sdist created by python2.6 could stillbreak when the end user is using python 2.4. [kiorky] 10.13. 3.39 (2012-09-26)
zest.releaser Documentation, Release 3.51.dev0
10.20 3.32 (2012-03-09)
10.21 3.31 (2012-02-23)
• Fixed test for unadvised egg_info commands on tag, which could result in a ConfigParser error.
10.22 3.30 (2011-12-27)
• Added some more PyPI classifiers. Tested with Python 2.4, 2,4, 2.6, and 2.7. [maurits] • Moved changes of 3.15 and older to docs/HISTORY.txt. [maurits] • Added GPL license text in the package. [maurits] • Updated README.txt. Added MANIFEST.in. [maurits] 10.23 3.29 (2011-12-27)
• In postrelease create a version number like 1.0.dev0. See • Offer to cleanup setup.cfg on the tag when releasing.
tag_svn_revision options in a release usually. [maurits] • For convenience also print the tag checkout location when only doing a release (instead of a 10.24 3.28 (2011-11-18)
• Git: in pre/postrelease only check for uncommitted changes in files that are already tracked. [mau- 10.25 3.27 (2011-11-12)
• Postrelease now offers (=asks) to push your changes to the server if you’re using hg or git.
• Support for some legacy projects, often converted from CVS, have multiple subprojects under a single trunk. The trunk part from the top level project isn’t erroneously stripped out anymore.
Thanks to Marc Sibson for the fix.
Chapter 10. Changelog for zest.releaser
zest.releaser Documentation, Release 3.51.dev0
10.26 3.26 (2011-11-01)
• Added sanity check before doing a prerelease so you are warned when you are about to commit on a tag instead of a branch (or trunk or master). [maurits] 10.27 3.25 (2011-10-28)
• Removed special handling of subversion lower than 1.7 when searching for the history/changes file. In corner cases it may be that we find a wrong HISTORY.txt or CHANGES.txt file when youhave it buried deep in your directory structure. Please move it to the root then, which is the properplace for it. [maurits] • Fixed finding a history/changes file that is in a sub directory when using subversion 1.7 or higher 10.28 3.24 (2011-10-19)
• Note: you may need to install setuptools_subversion when you use subversion 1.7. If you suddenly start missing files in the sdists you upload to PyPI you definitely need it. Alternatively: set up aproper MANIFEST.in as that method works with any version control system. [maurits] • Made compatible with subversion 1.7 (the only relevant change is in the code that checks if a tags or tag directory already exists). Earlier versions of subversion are of course still supported.
[maurits] • Code repository moved to github: [maurits] 10.29 3.23 (2011-09-28)
• Fixed opening the html long description in longtest on Mac OS X Lion or python2.7 by using 10.30 3.22 (2011-05-05)
• Allow specifying a tag on the command line when using lasttaglog or lasttagdiff, to show the log or diff since that tag instead of the latest. Useful when you are on a branch and the last tag wasfrom trunk. [maurits] 10.31 3.21 (2011-04-20)
• Added lasttaglog command that list the log since the last tag. [maurits] • Fix Mercurial (hg) support. As spreaded_internal should be set to False (as it happens with git) • Accept a twiggle (or whatever ‘~’ is called) when searching for headers in a changelog; seen in some packages (at least zopeskel.dexterity). [maurits] 10.26. 3.26 (2011-11-01)
zest.releaser Documentation, Release 3.51.dev0
10.32 3.20 (2011-01-25)
• Also allowing CHANGES.rst and CHANGES.markdown in addition to CHANGES.txt.
10.33 3.19 (2011-01-24)
• No longer refuse to register and upload a package on pypi if it is not there yet, forcing people to do this manually the first time. Instead, we ask the question and simply have ‘No’ as the defaultanswer. If you specify an answer, we require exactly typing ‘yes’ or ‘no’. The idea is still to avoidmaking it too easy to release an internal package on pypi by accident. [maurits] 10.34 3.18 (2010-12-08)
10.35 3.17 (2010-11-17)
• When the package that is being released neither has a setup.py nor a setup.cfg, use No as default answer for creating a checkout of the tag. [maurits] 10.36 3.16 (2010-11-15)
• For (pypi) output, also show the first few lines instead of only the last few. [maurits] • See if pypirc or setup.cfg has a [zest.releaser] section with option release = yes/no. During the release stage, this influences the default answer when asked if you want to make a checkout of thetag. The default when not set, is ‘yes’. You may want to set this to ‘no’ if most of the time youonly make releaser of internal packages for customers and only need the tag. [maurits] • Specify bazaar (bzr) tag numbers using the ‘tag’ revision specifier (like ‘tag:0.1‘) instead of only the tag number (0.1) to add compatibility with earlier bzr versions (tested with 2.0.2). [maurits] 10.37 3.15 (2010-09-10)
• Read pypi config not only from the .pypirc file, but also from the setup.cfg file of the package.
10.38 3.14 (2010-08-26)
• experimental support for git svn tagging, fully test-covered [chaoflow] • fail if no tag was created, not test-covered [chaoflow] Chapter 10. Changelog for zest.releaser
zest.releaser Documentation, Release 3.51.dev0
• svn available_tags method: intercept ‘Repository moved’ note in svn info and stop processing 10.39 3.13 (2010-08-16)
• Fixed check that tested whether a package was already available on pypi, as the pypi implemen- tation changed slightly. We now just check for a 404 status. Patch by Wolfgang Schnerring.
[maurits] 10.40 3.12 (2010-07-22)
• Added extra entry point for the release step: after_checkout. When this is run, the middle entry point has been handled, the tag has been made, a checkout of that tag has been made and weare now in that checkout directory. Idea: Jan-Wijbrand Kolman. [maurits] • Fix: in the zest.releaser.releaser.after entry point data, pass the ‘tagdir’ value (if a checkout has been made). Patch by Wolfgang Schnerring, thanks! [maurits] • Fixed tests to also pass with slightly newer git. [maurits] 10.41 3.11 (2010-06-25)
• Small tweak: allowing zc.rst2’s “rst2 html” in addition to docutils’ own “rst2html”.
10.42 3.10 (2010-06-15)
• Fix : when running ‘release’ with python2.6 against a private egg server, the distutils ‘register’ command would run against PyPI while ‘upload’ command would run against private server. (-roption needs to be stated twice) [gotcha] 10.43 3.9 (2010-06-11)
• Again at the end of a fullrelease report the location of the directory containing the checkout of the 10.44 3.8 (2010-05-28)
• Also allowing CHANGES in addition to HISTORY.txt and CHANGES.txt as a history file- name. Keeps several Django packages happy.
10.45 3.7 (2010-05-07)
• Added support for bzr. Fixes [menesis] 10.39. 3.13 (2010-08-16)
zest.releaser Documentation, Release 3.51.dev0
10.46 3.6 (2010-04-13)
• A version=’1.0’, string inside the setup() call no longer has non-pep8 spaces around the • 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 withcollective.dist). Only ascii is allowed in the long_description if you want to avoid problems at onepoint or another. [maurits] 10.47 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] 10.48 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 thereis no ‘.svn’ folder in SVN repositories. [vincent] 10.49 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] 10.50 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 (and pointing at that in the 10.51 3.1 (2009-11-27)
• Added documentation for entry points. [reinout] Chapter 10. Changelog for zest.releaser
zest.releaser Documentation, Release 3.51.dev0
10.52 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] 10.53 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 10.54 2.11 (2009-11-25)
• Added /tag besides /tags for subversion [gotcha] 10.55 2.10 (2009-10-22)
• Lots of internal refactoring and small fixes. [reinout] • Started tests. zest.releaser went from 0 to 94% coverage. [reinout] 10.56 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 docu-mentation 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 asbeing on pypi as the svn directory name was feedfeeder. [maurits] 10.57 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 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] 10.52. 3.0 (2009-11-27)
zest.releaser Documentation, Release 3.51.dev0
10.58 2.8 (2009-08-27)
• Fixed the release command when used in a french environment. In French “svn info” returns ‘URL :’, not ‘URL:’. [vincentfretin] 10.59 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] 10.60 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] 10.61 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 packagesto pypi. [maurits] 10.62 2.4 (2009-05-15)
• Factored release.py out into a new pypi.py, solving a few possible problems with missing or mis- 10.63 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] 10.64 2.2 (2009-05-11)
• postrelease: suggestion for next version after 1.1.19 is not 1.1.110, but 1.1.20. [maurits] Chapter 10. Changelog for zest.releaser
zest.releaser Documentation, Release 3.51.dev0
10.65 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 10.66 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] 10.67 1.13 (2009-03-17)
• Also looking for CHANGES in addition to HISTORY.txt and CHANGES.txt as some packages • 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] 10.68 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 ofscrolling. [reinout] 10.69 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 thereal package/name/HISTORY.txt. [maurits] 10.70 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] 10.65. 2.1 (2009-04-09)
zest.releaser Documentation, Release 3.51.dev0
10.71 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 10.72 1.8 (2009-02-23)
• Added ‘longtest’ command that renders a setup.py’s long description and opens it in a web 10.73 1.7 (2009-02-16)
• Supporting alternative history version header format: ‘version - date’. [reinout] 10.74 1.6 (2009-02-14)
• Patch by Michael Howitz: sys.executable is used instead of a string that doesn’t work on every 10.75 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] 10.76 1.4 (2008-10-23)
• Fixed missing import of utils. [maurits] 10.77 1.3 (2008-10-23)
• Moved stabilize script to zest.stabilizer so that zest.releaser is just for releasing individual pack- • Allowing ‘-v’ option on all commands: it gives you debug-level logging. [reinout] Chapter 10. Changelog for zest.releaser
zest.releaser Documentation, Release 3.51.dev0
10.78 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] 10.79 1.1 (2008-10-15)
• Cleaned out zest-specific stuff. Cleaned up ‘release’. [reinout] 10.80 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: Prod- ucts.feedfeeder, which has a buildout.cfg and so can have a parts directory with lots of version.txtfiles. [maurits] 10.81 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] 10.82 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] 10.83 0.7 (2008-09-26)
• fullrelease: hopefully fix a ‘commit on tag’ bug by sleeping three seconds before doing the post 10.78. 1.2 (2008-10-16)
zest.releaser Documentation, Release 3.51.dev0
10.84 0.6 (2008-09-26)
• Added fullrelease script that does a prerelease, actual release and post release in one go. [maurits] 10.85 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] 10.86 0.4 (2008-09-26)
10.87 0.3 (2008-09-26)
• Postrelease: Better injection of history. Various other robustness fixes.
10.88 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 • release: Refactored so release.py has the ‘main’ function required by setup.py. [maurits] 10.89 0.1 (2008-09-24)
• Got a basic version of the prerelease script working (version check, history file updating, commit- • Started by copying the guidelines script. [reinout] Chapter 10. Changelog for zest.releaser

Source: https://media.readthedocs.org/pdf/zestreleaser/latest/zestreleaser.pdf