Revision Numbering
As with many others things, we have chosen our own method of numbering revisions. The scheme is used on a variety of items, such as stand-alone software modules, software packages, documents, and so forth.
General Syntax
All revision numbers used for Greytower products follow the same syntax, as illustrated by this RFC 2234 compatible BNF grammar:
revision ::= version DELIM release (DELIM | status) patch
version ::= 1*DIGIT
release ::= 1*DIGIT
patch ::= 1*DIGIT
status ::= (a|b)
DIGIT ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
DELIM ::= .
This can be conclusively parsed by the following Perl-compatible regular expression:
(\d+)\.(\d+)(\.|a|b)(\d+)
Cycles
There are three distinct release cycles:
- Development. The item is being worked on, but has not yet reached such a level that it can be tested with any reliable results.
- Testing. The item has been developed to such a level that it can be tested against real life data, or reviewed by others in the case of documents. The item is not yet ready for active deployment.
- Production. The item has been developed to the point that it can be used with consistent results.
Each cycle is easily identified from the revision string by observing the status code.
Status Code
There are three status codes - one implicit, existing only for the sake of consistency. If the status code part of a revision string is
- "a" (alpha) - then the item is in its development phase, and must not be relied upon to produce consist or even correct results.
- "b" (beta) - then the item is in the testing phase; something which must be taken into account when evaluating the correctness of data.
- missing, then the item is in production and should be relied upon, or considered authoritative in the case of documents.
Revision Changes
Changing the revision string for an item follows a set of simple rules:
Setting the Initial Revision
Once an item is released for the first time, it is given the revision
string 1.0a0. Typically, this revision is released after
some initial work has been done.
Minor Changes to an Item
When an item change in a minor way, such as the correction of a
grammatical or syntactical error in a document, or a bugfix in a
program, the patch section of the revision string should
be incremented by one (1). Given an initial revision and a minor
change, 1.0a0 would change to 1.0a1.
Changing the Status
When an item has gone through a number of such changes, and is deemed
mature enough to start testing with real world data, the
status part of the revision string is changed from
a to b and the patch level reset.
Given a revision of 1.0a15, a status change would yield
1.0b0.
When the item is deemed free enough of bugs to go into production,
the status section is removed, and the patch
level reset. Given a revision of 1.0b29, such a change would
yield 1.0.0
Releases and Versions
The release and version fields are only
changed in production level items.
release is changed when sections/functionality is added
or removed, as opposed to bugs/errors being corrected. Given a revision
of 1.0.0, adding functionality/sections would yield
1.1.0
version is changed when the program/document is re-written
from scratch. Given a revision of 1.1.0, such a rewrite would
yield 2.0a0 and a restart of the cycle.
Packages
Packages – that is collections of programs or libraries that belong to a common system (such as PetiteCGI) – will have revisions that identify the entire package. The various parts of the package will have separate revision strings.
Package Names
Software packages are named according to the following scheme:
PackageName-revisionstring.tar.gz
Programs
Stand-alone programs and libraries are giving separate revision strings following the standard pattern.
Program and Library Names
Whilst stand-alone programs are named according to the same scheme as
packages – see above – libraries is another matter. As we
mostly do internal work using Perl, all our libraries are named
with the .pm extension. Distributions of such libraries
follows the pattern:
LibraryName.pm-revisionstring.tar.gz