HowTo: Release iHRIS Software 4.0

Creating a New Release

The tool to handle releasing is I2CE/tools/release.php. The release.php script has two functions -- to bump the version numbers of any modules that have changed since the last release, and to create tarballs of the various software components.

Prerequisites

Please run <source lang='bash'> sudo apt-get install pcregrep </source>

Bazaar Branches and Subdirectories

The release.php script operates on the bazaar branches that contain your code. It assumes that every subdirectory from which release.php is being run is a potential bazaar branch to perform a release on. It will cycle through each of the bazaar branches/subdirectories and warn about any uncommitted changes.

The top-level module is the module at the root of the bazaar branch. If release.php cannot find a module at the root of a bazaar branch, then that branch/sub-directory is ignored.

Versioning

Versioning is based on a three part versioning system, XXX.YYY.ZZZ. The XXXX is "major" part, YYYY is the "sub-major part" and ZZZ is the "minor" part. For example version 4.0.12 has a major version number of 4, a sub-major version number of 0 and a minor version number of 12. Anything that follows the ZZZZ is ignored for the purposes of releasing.

Tagging

The release.php script tags each of the bazaar branches to indicate which revision number was used for the release. The tag follows the form "XXX.YYY.ZZZ-release" so you might see a "4.0.12-release" as a tag on that revision.

Version Bumping

If there has not been yet been a release of a branch (detected through the release tag), the release version will the release version of the top-level module.

If however, there already has been a release, then the release.php script will ask you if you want to increase the version number of a module in either of these scenarios:

• Top-Level Module: The top-level module can be version bumped if the the XXX.YYY.ZZZ part of he current version of the top-level module is less than or equal to the version number of the most recent release tag.
• Sub-Modules: Any sub-module can be bumped if it has had changes to its files since the last release and has the same major and sub-major version numbers as the top-level module/

If a module is going to be version bumped, it will be bumped to the version that it is going to be released on.

Release Branches

The release.php will also optionally create and update "release" branches on launchpad. These take the form of

lp:~<<launchpad team or user>>/<<top-level module>>/XXX.YYY-release

and

lp:~<<launchpad team or user>>/<<top-level module>>/XXX.YYY.ZZZ-release

so you have any easy reference to the current minor release.

Tarballs

Tarballs are created for each of the bazaar branches which include all the files except any packaging or bazaar files. The version number is put in the name of each tarball and saved, by default, to the subdirectory ihris-release of your home directory. These tarballs are suitable for distribution and upload to launchpad (which must be done manually at this point)

Translations

By default, the release tarballs include the translations for the following locales: fr, pt, pt_BR,sw, et, it. If you wish to modify this list, you can do so using ---locales=XX,YY,ZZ

Debian Packaging

The tool to handle packaging is I2CE/tools/debian.php and is designed to function for several packaging scenarios. You do not need to make a release in order to make debian packages

Ubuntu Versions

Packages are built by default for the lucid and maverick versions of ubuntu. Packages will not work under karmic or earlier versions. The ubuntu versions can be specified by

--ubuntus=XXX,YYY,ZZZ

Package Naming

A .deb package is produced for each module. The name of the package is based on the module name but conforms to the debian package name requirements. Briefly all package names use have ihris+ as a prefix, are lower case and many special characters are either removed or replaced.

Because the names of a debian packages live in a global space, it is very important that you prefix your module names with something to distinguish them. For example, if you are working in Tanzania as part of the Tanzania HRIS team, your modules could be named somehthing like "tzhris-leave-management" and "tzhris-person." This will ensure that your module does not have the same name as a similar (but different) module in for example, Botswana. If you don't do this, apt-get can act in a crazy irrational manner

Versioning

The versioning is much more complicated for debian packaging than for releases. It conforms to the debian versioning with no epochs being used.

The version of a module has several potential pieces and follows one of the following formats:

• $ModuleVersion~$Ubuntu This is the default version used. Here $ModuleVersion is the full version of the module, not just the major,sub-major and minor parts (for example 4.0.12.22), and $Ubuntu is the ubuntu release this is being packached for: lucid or maverick
• $ModuleVersion~$Ubuntu-$DebianVersion This is used if there was a mistake in the packaging you need to repackage with no underlying change to the module. This is also used in case you want to update the translations for a module. Here $DebianVersion is at least 1 and is determined based on the already published version of your .deb package.
• $ModuleVersion+$RevisionNumber~$Ubuntu This is intended to be used between releases. Here $RevisionNumber is the difference between the last revision number at which the module was changed and the revision number of the last release.
• $ModuleVersion+$RevisionNumber~$Ubuntu-$DebianVersion This as in the previous one, but indicates a repackaging of the previous.
• $ModuleVersion+$RevisionNumber.$Incremental~$Ubuntu This is similar to the last one, but is used in the case that there has already been a non tagged-release packaging

PPA

The PPA, or Personal Package Archive is where we will store all of the debian packages. It can be attached to either a launchpad user or team. You can either specify this at the command line via

--launchpad-login=<<Luanchpad User or Team>> 

or you will be asked for it when needed. All debian packages produced will be stored in the PPA:

~<<Luanchpad User or Team>/ihris-ppa

Modules

By default, all module are built but you can specify which modules to build by using the --pkg-modules=XXX,YYY,ZZZ command-line directive.

Regular Modules

Regular (non-site) modules are installed under /usr/ihris/lib/XXX.YYY where XXX.YYY is the major.sub-major release of i2ce on which the module is based off of/from which the debian.php was called. For example 4.0 or 4.1.

Site Modules

The packaging a site is handled differently than a regular module. Sites can be in one of two places in a bazaar:

• as the top-level module with a pages subdirectory
• as a module living under the sites subdirectory of the top-level module. Each should also have a pages subdirectory,

Requirements for a site are:

• existence of the pages sub-directory with:
  • index.php
  • htaccess.TEMPLATE
• each site modules should require the module i2ce-site which will make sure all php necessities are installed.

The creation of a site package does a few things:

• creates a database based on the module name
• creates a database user based on the module name
• uses the htaccess.TEMPLATE file to create a file to put under /etc/apache2/conf.d
• gets installed under /var/lib/iHRIS/sites/XXX.YYY where XXX.YYY is the major.sub-major release of i2ce on which the module is based off of/from which the debian.php was called.

Translations

All translations for a module the locales it,sw,fr,pt,pt_BR,et are added automatically to the module. You can change this by setting the --locales variable at runtime

Development and Release Candidates

If you specify the command line parameter --rc=RC, you can create development or release candidates of the packages. These are intended to be used for development and testing purposes, and not for production. In this case the following changes are made to the standard releaes

• The PPA is ihris-RC-ppa
• Package names are ihris-RC+module
• All modules are installed under /usr/lib/iHRIS-RC/lib/XXX.YYY
• All sites are installed under /var/lib/iHRIS-RC/sites/XXX.YYY
• The database user is ihrisRCmodule

WARNING: It is intended that you should be able to various RC and release packages side by side but this has not been tested. I think there will be an issue with the apache.conf files produced from the htaccess.TEMPLATE files. There may also be an issue with the database name.

Debian Packaging Scenarios

Release

This is done just after running the 'release.php' script.

Updating Translations for a Release

In this case, you only want to update the translations. You can use debian.php to revert everything back to the last release except the translation files (.pot and .po files).

Testing/Release Candidate

You should simply select to package all revisions