Package Upgrades

Brief summary on how package upgrades work

Created by: xing, Last modification: 01 Feb 2009 (08:20 UTC)
Since version bitweaver version 2.5 individual packages can be updated individually allowing quicker and more organic development of bitweaver. Here i describe the basics of how these upgrades work. to view examples of upgrade files, you can view the ones provided in sample/admin/upgrades/*.

Package release

When you first release a package, you will not have any updates in that package and you can set your package version in your <package>/admin/schema_inc.php file using the following method:

Setting package version in schema_inc.php


<?php
// Version - now use upgrades dir to set package version number.
$gBitInstaller->registerPackageVersionSAMPLE_PKG_NAME'0.5.1' );
?>


As you add new upgrades to your package, you do not need to update this number as the installer will automagically detect the most recent upgrade and apply that number on a first install.
It is however necessary to keep your schema_inc.php file up to date since no upgrades will be applied on a first install.

Using a simple example:
You have a package called sample and you have a table in that package called sample_foo. To rename the table from sample_foo to sample_bar you need to add an appropriate upgrade file (see below) and rename sample_foo to sample_bar in your schema_inc.php file.

Upgrade files

Upgrade files are kept in <package>/admin/upgrades/<version>.php. this keeps files small and allows us to only load files that are needed during the upgrade process.

Version Numbers

Version numbers are in accordance with php version numbers that we can make use of version_compare() (as explained previously regarding the bitweaver version number). this means that version numbers are of the form:
format: #.#.#-<status>
e.g.: 3.4.5-beta
status values in order of release order are as follows:
  • dev
  • alpha
  • beta
  • RC# (RC + release candidate number)
  • (no status)
  • pl
If you use an invalid version number, the upgrade will not be recognised by the installer and it will not be applied.

Package Requirements

You can also register package requirements in your schema_inc.php file. You can register the minimum and maximum version of a package your package has been tested with. The requirement versions you register are always inclusive i.e.: if you register that your package works with a package minimum version 1.1.1 and maximum version 2.2.2 it will use any version between 1.1.1 and 2.2.2 including 1.1.1 and 2.2.2 as good version numbers.

This example is taken from liberty:

liberty/admin/schema_inc.php


<?php
// Package Requirements
$gBitInstaller->registerRequirementsLIBERTY_PKG_NAME, array(
    
'users'     => array( 'min' => '2.1.0' ),
    
'kernel'    => array( 'min' => '2.0.0' ),
    
'themes'    => array( 'min' => '2.0.0' ),
    
'languages' => array( 'min' => '2.0.0' ),
    
'storage'   => array( 'min' => '0.0.0' ),
));
?>
</status></version></package></package>