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

Example Release

<source lang='bash'>

</source>

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

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.

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

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.