Difference between revisions of "Versioning"

From ProgClub
Jump to: navigation, search
(→‎Software constants: note about hard coded version constants)
(code to explain version component calculation...)
Line 32: Line 32:
 
  define( 'VERSION_REVISION', 1234 );
 
  define( 'VERSION_REVISION', 1234 );
  
After loading the config file the full version must be calculated. If VERSION_BUILD is undefined then the version is:
+
After loading the config file the full version must be calculated. E.g.:
  
  define( 'VERSION', VERSION_BASE );
+
  if ( defined( 'VERSION_BUILD' ) ) {
 
+
Otherwise if the VERSION_BUILD is specified, if the VERSION_REVISION is unspecified the VERSION_REVISION needs to be calculated by parsing the output of 'svn info' for the project. If the VERSION_REVISION can't be determined it is zero.
+
  if ( ! defined( 'VERSION_REVISION' ) ) {
 
+
define( 'VERSION_REVISION', parse_svn_info_revision() );
+
    // note: parse_svn_info_revision() returns zero on error
 
+
    define( 'VERSION_REVISION', parse_svn_info_revision() );
As we now have the BUILD and REVISION numbers the software version is:
+
 
+
  }
define( 'VERSION', VERSION_BASE . '-' . VERSION_BUILD . '.' . VERSION_REVISION );
+
 +
  define( 'VERSION', VERSION_BASE . '-' . VERSION_BUILD . '.' . VERSION_REVISION );
 +
 +
}
 +
else {
 +
 +
  define( 'VERSION', VERSION_BASE );
 +
 +
}
  
 
Happy days!
 
Happy days!
  
 
p.s. If your program is just an application you can use constants such as VERSION_MAJOR, VERSION, etc. If your program is a library you should scope your constants, e.g. PHPBOM_VERSION_MAJOR, PHPBOM_VERSION, etc.
 
p.s. If your program is just an application you can use constants such as VERSION_MAJOR, VERSION, etc. If your program is a library you should scope your constants, e.g. PHPBOM_VERSION_MAJOR, PHPBOM_VERSION, etc.

Revision as of 14:17, 17 February 2017

OK, here's the spec for how version numbers should be managed across ProgClub projects (from now on).

We will endeavour to be compatible with Semantic Versioning (v2.0.0 at time of writing).

So our semantic versioning is: MAJOR.MINOR.PATCH[-BUILD.REVISION]

Our MAJOR.MINOR component will be resident in the Subversion path, e.g. project/branches/3.0 for MAJOR.MINOR version 3.0. The MAJOR and MINOR version numbers will also be in software constants (see below).

Our PATCH version will not be in the Subversion path, but will be in a software constant (see below).

Our BUILD is one of, e.g. 'dev', 'alpha', 'beta', 'test', 'prod', etc. The BUILD is specified in the config file, not in the software. If the BUILD is unspecified the BUILD.REVISION component of the version number is omitted.

Our REVISION is the Subversion revision number of the software. The REVISION is calculated by running 'svn info' and retrieving the 'Revision:' value. The 'svn info' command can be run at install time with the REVISION stored in the config file, or if there is no setting in the config file then 'svn info' can be run at runtime. If the REVISION cannot be determined it is zero.

Software constants

So minimally we'd have:

define( 'VERSION_MAJOR', 3 );
define( 'VERSION_MINOR', 0 );
define( 'VERSION_PATCH', 0 );
define( 'VERSION_BASE', VERSION_MAJOR . '.' . VERSION_MINOR . '.' . VERSION_PATCH );

The above four constants are "hard coded" into the software by the developer. It's the developer's responsibility to ensure that the values are correct and in sync with the project branch name in the repository.

Then we'd need to load our config file, which may have a BUILD type, e.g.:

define( 'VERSION_BUILD', 'dev' );

There might also be a REVISION in the config file, e.g.:

define( 'VERSION_REVISION', 1234 );

After loading the config file the full version must be calculated. E.g.:

if ( defined( 'VERSION_BUILD' ) ) {

  if ( ! defined( 'VERSION_REVISION' ) ) {

    // note: parse_svn_info_revision() returns zero on error
    define( 'VERSION_REVISION', parse_svn_info_revision() );

  }

  define( 'VERSION', VERSION_BASE . '-' . VERSION_BUILD . '.' . VERSION_REVISION );

}
else {

  define( 'VERSION', VERSION_BASE );

}

Happy days!

p.s. If your program is just an application you can use constants such as VERSION_MAJOR, VERSION, etc. If your program is a library you should scope your constants, e.g. PHPBOM_VERSION_MAJOR, PHPBOM_VERSION, etc.