Automatic Tarball Creation

Prerequisites

The tarball for a Geeklog release is created automatically and also added to the File Management submission queue on www.geeklog.net. In order to perform a Geeklog release, you need

• commit permission to the Geeklog repository (to tag the release)
• access to the File Management submission queue (to actually publish the tarball)
• a Geeklog release should be accompanied by an announcement on www.geeklog.net, so you also need to be able to publish a story (or submit one and ask someone with moderator access to publish it)

Details

Tagging

The convention is that all actual Geeklog releases (beta, release candidate, security release, or "normal" release) are tagged with a tag that starts with geeklog_, followed by the version number (where dots are replaced by underscores) and an appendix ('b' + number for betas, 'rc' + number for release candidates, 'sr' + number for security releases, or '_stable' for the final release).

It is important to stick to these naming conventions! Tags that start with "geeklog" should be considered reserved. Feel free to tag any revision that somehow marks an important point in Geeklog development, but unless it is a release version, its tag should not start with "geeklog".

The script that creates the tarball may fail if the version number part of the tag isn't correct. So while - from a user's point of view - this is mostly a convention, getting the version number right is also important for the process to succeed.

Tarball Creation

The geeklog-release job in Jenkins will run every 15 minutes. It checks for new tags. When a new tag is found and that tag starts with geeklog_, it will start the creation of the tarball. The actual steps that it performs are part of the Jenkins job but follow those in the mkdist.sh script from the tools repository, i.e. it

• checks out the tagged version
• removes any files and directories that shouldn't be in the tarball
• adds the PEAR classes
• figures out what the previous release was and creates the changed-files list of files that changed since that previous release
• creates the tarball

Publishing

After the tarball has been created, it is automatically copied over from the project server to the server that hosts the Geeklog website. It is also added to the File Management's submission queue.

The description of that file contains the correct version number, file size, and md5 checksum. When approving this submission, make sure to update the file's description with a short text describing what the release is about (e.g. a beta) or what the most important new features are.

Releasing from a branch

When releasing a version that is on its own branch, e.g. a security or bugfix release, Jenkins' Mercurial plugin gets into the way somewhat. The plugin will always check out a branch, instead of just updating the repository to whatever the latest changes are. Since we will normally want to release from HEAD, the plugin is configured to check out HEAD. This means that when releasing from a branch

1. the tag must be set in HEAD (not on the branch)
2. another change must be committed after the tag (to be clarified: will any commit in HEAD do, or do we always need to merge the changes from the branch into HEAD?)

Releasing

So here's how you trigger a release:

• make sure your local repository is up to date
• figure out the revision you want to tag (e.g. use hg log to view the history)
  • to refer to the latest local revision, you can always use the symbolic name tip
• tag that revision, e.g.
  hg tag -r 8765 geeklog_1_7_5_stable or
  hg tag -r tip geeklog_1_8_6sr2
• do: hg tags and check that your tag is there and matches the naming conventions
• hg push
• The Jenkins release job runs every 15 minutes and then takes a few minutes to process. So you should see a result after max. 30 minutes or so.
• Log into your account on www.geeklog.net and check that the release tarball is in the submission queue for the File Management plugin.
• Approve it.
• Go to the list of current Geeklog releases, edit any outdated versions and move them to the "Geeklog -- old versions" category.
• Post the release announcement.

Fixing Things

Mistakes happen. Don't sweat it.

Tagging

Like normal commits, tags have to be pushed before they end up in the Geeklog repository (and are seen by Jenkins). So after tagging a release, double-check that you've got the formatting correct. Do a

hg tags

and compare the tag names.

At this point, fixing things is easy. Simply do:

hg rollback

and tag again.

Cleanup

If you happened to be pushing a wrong tag, you may have ended up with a misnamed tarball in the File Management submission queue. Simply delete it.

To clean up the tagging, you have the option of removing the tag:

hg tag --remove wrong_tag_name_here

Note: Jenkins also keeps a copy of the last tarball as a so-called "artifact". After removing a tag, this artifact will still be available from Jenkins (until another release job creates a new artifact). This shouldn't really be a problem, though.

If the name was correct but you tagged the wrong revision, you can force the tag into the right place:

hg tag -f -r revision-here tag_name_here

i.e. use the same tag name again, but with the correct revision now and the -f flag to force it to be applied again. This will also trigger the geeklog-release job again and create a new tarball with the same name.