Oslo Library Release Process
See Oslo/VersioningPolicy for guidelines for choosing version numbers.
Because Oslo libraries tend to generate releases far more often than the integrated projects, we use "post-release" tracking rather than major milestone predictive tracking. Release series are named after the current development cycle code name, using all lower case letters. Each library should also have a single open "next-$series" milestone within the series. Active work is placed in the milestone, and the milestone is renamed as part of the release process to indicate that the completed work was done in the given release.
For example, oslo.log has a "kilo" series and a "next-kilo" milestone. Blueprints and bugs are added to "next-kilo" as work begins. When release 0.1.0 of oslo.log is tagged, the "next-kilo" milestone is renamed to "0.1.0" and a new "next-kilo" milestone is created. Any blueprints or bugs *not* completed as part of the 0.1.0 release is moved to the new milestone and work continues.
The oslo-incubator uses major milestone tracking ("kilo-1", "kilo-2", etc.) because it is not technically released and because we use the oslo-incubator project for blueprints and specs that are not related to a single library.
Installing Release Tools
The release management team has created some tools to help manage our releases. To install the tools, check out a copy of the openstack-infra/release-tools git repository, create a virtualenv, and install the dependencies:
$ git clone git://git.openstack.org/openstack-infra/release-tools $ cd release-tools $ virtualenv .venv $ source .venv/bin/activate $ pip install -r requirements.txt --allow-external lazr.authentication --allow-unverified lazr.authentication
Setting Up GPG
OpenStack releases rely on GPG-signed tags in the git repository. You will need a GPG key configured on the system where you are going to tag releases. It is good to have your key signed by other members of the community to establish a web-of-trust. There are usually in-person meetings at the summits and mid-cycle meetups to take care of key signings.
If your default Git commit email address is not included in your gpg key, you will need to add it in order to continue (or change your default git commit address). This can be done using the following steps, based on the instructions in this blog post, and will not invalidate your key:
- $ gpg --edit-key firstname.lastname@example.org
- At the gpg command line, type "adduid"
- When prompted, enter your real name and address. These must match your git commit settings.
- Leave the comment field blank (this is a change from the blog post instructions).
- If everything looks correct, hit 'o'
- Back at the gpg command line, press the number associated with your newly added uid.
- Enter 'trust'
- Press 5 to trust yourself ultimately
- Type 'quit' at the gpg prompt and answer 'y' when it asks you to save your changes.
Setting up Launchpad
The release tool connects to launchpad, which requires oauth authorization. Setting this up usually requires a web browser, and some users have experience trouble with console browsers such as lynx. You may, therefore, want to run the release scripts on your local system where a regular GUI browser is available, instead of on a remote server where only the terminal is available to you.
Setting up Gerrit Permissions
After the release tool checks out the code repository specified and creates the signed tag, it pushes the tag up to gerrit. You need special permissions to push tags to gerrit, so make sure you are in the release team for the project you are trying to release. Another member of the same gerrit release team, or the infra team, can help you set this up.
Releasing a Library
Use the oslo_release.sh script to tag a release and update launchpad.
$ ./oslo_release.sh Usage: ./oslo_release.sh series version SHA project Example: ./oslo_release.sh juno 1.0.0 HEAD oslo.rootwrap
The first time you run this, it will open a browser window where Launchpad will ask you what permissions to grant the application. The easiest option is just to allow all.
After the repository is tagged, the release tool updates all of the closed bugs for the project, ensuring they are in the next-$series milestone. It then renames that milestone to the version number you have specified, making release notes and tracking easier.
At that point the script prints a message like "Fix any leftover bugs manually and press key to continue...". STOP HERE AND GO LOOK AT LAUNCHPAD.
This is your opportunity to fix any bugs that need to be marked as "Fix Released" but for which the API timed out (this happens frequently when too many projects are associated with the same bug). It is also your opportunity to move any bugs that aren't closed to a different milestone, before the current milestone is closed.
First, create a new next-$series milestone by clicking the "Create milestone" link on the series page.
Next, if there are any blueprints or bugs in the version milestone that are *not* completed, move them to next-$series.
Finally, if there are any bugs in the version milestone that are completed but not marked as "Fix Released", update their state. You may have to try several times if there are timeout errors.
Only when this is done, go back to the terminal and press return to continue the process. At this point, the script closes the old milestone so no new items can be added to it.
Send Release Notes
We generate release notes for library releases directly from the git logs, so refresh your local sandbox:
$ git pull
Get the changes in the release:
$ git log --abbrev-commit --pretty=oneline --no-merges $prevrel..$relnum
Email the details to the openstack-dev mailing list, for example:
The Oslo team is pleased to announce the release of oslo.vmware 0.7.0. This release includes several bug fixes as well as many other changes: 1661a0a Updated from global requirements 33f6002 Imported Translations from Transifex 8b1f97b Do not log when reraising an exception 575fd70 Imported Translations from Transifex 0b7ff54 Updated from global requirements 8ed3d53 Add unit test for VC 5.1 web fault handling 776c20d Fix to get exception detail with vCenter 5.1 62d0ba7 Download image API to bypass vCenter 6aa427d Updated from global requirements 84a39fb Updated from global requirements e25af91 Enable the PBM WSDL to be updated 9f6f2a3 Support building wheels (PEP-427) 73d1160 Fixup autoindex.rst only if it exists 42eab0c Supress error logs when exception is thrown 2350257 Fix handling of fault details 7591589 Fix UnboundLocalError during WebFault handling 89d0131 Use faultstring attribute in suds.WebFault.fault 54455f2 Imported Translations from Transifex 95e84eb Fix the log message for progress 264e428 Add API to get the entity inventory path ee4d9c0 VimExceptions need to support i18n objects df59368 Switch to using oslo.utils e55e677 Use custom transport adapter for file URLs 1c2987b getText can be called only when doc is not None def85dd Updated from global requirements 80057e4 Add unit test for suds cache expiration a3e493a Add a memory based shared cache 6a72bf1 Updated from global requirements 4bd0b4c VMware: Enable vCenter SSL certificate validation For more details, please see the git log history below and https://launchpad.net/oslo.vmware/+milestone/0.7.0 Please report issues through launchpad: https://launchpad.net/oslo.vmware ---- $ git log --no-merges 0.6.0..0.7.0 commit 1661a0af8ce14edbfb00fed0a30a3b9135517d93 Author: OpenStack Proposal Bot <email@example.com> Date: Wed Nov 5 08:35:10 2014 +0000 Updated from global requirements Change-Id: I88286d9ef8ff5fc5210a9ed87bacffd60ff78a56 ...