View source for 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 [[Tags and Branches|tagged]] with a tag that starts with <tt>geeklog_</tt>, 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 [http://project.geeklog.net:8080/job/geeklog-release/ 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 <tt>geeklog_</tt>, 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 <tt>mkdist.sh</tt> script from the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ 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 <tt>changed-files</tt> 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
# the tag must be set in HEAD (not on the branch)
# 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 <tt>hg log</tt> to view the history)
** to refer to the latest local revision, you can always use the symbolic name '''tip'''
* tag that revision, e.g.<br><tt>hg tag -r 8765 geeklog_1_7_5_stable</tt> ''or''<br><tt>hg tag -r tip geeklog_1_8_6sr2</tt>
* do: <tt>hg tags</tt> and check that your tag is there and matches the [[Tags_and_Branches#Naming_conventions|naming conventions]]
* <tt>hg push</tt>
* The [http://project.geeklog.net:8080/job/geeklog-release/ 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 [http://www.geeklog.net/filemgmt/viewcat.php?cid=8 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
<pre>hg tags</pre>
and compare the tag names.

At this point, fixing things is easy. Simply do:
<pre>hg rollback</pre>
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:
<pre>hg tag --remove wrong_tag_name_here</pre>
'''Note:''' [[Jenkins]] also [http://project.geeklog.net:8080/job/geeklog-nightly/lastSuccessfulBuild/ 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:
<pre>hg tag -f -r revision-here tag_name_here</pre>
i.e. use the same tag name again, but with the correct revision now and the <tt>-f</tt> flag to force it to be applied again. This will also trigger the <tt>geeklog-release</tt> job again and create a new tarball with the same name.


[[Category:Internals]]