BlackBox Versioning Strategy

The versioning strategy for BlackBox distributions built by the BlackBox Framework Center is as follows:

The downloadable BlackBox packages carry a version information in their file names. The same naming convention applies for installable setup.exe files as well as for zipped packages that can be installed by unpacking the .zip file. Also the build-log file uses the same naming convention, which is defined below using an EBNF grammar.

FileName = "blackbox-" AppVersion ["." BuildNumber] + ("-setup.exe" | ".zip" | "-buildlog.html").

AppVersion = MajorVersion "." MinorVersion ["." PatchLevel] [DevelopmentStage].

DevelopmentStage = "-" ("a" | "b" | "rc") StageNumber.

AppVersion is maintained in a file named 'AppVersion.txt', which can be found in the directory 'appbuild'. The existence of this file in a branch signals that automatic building of that branch is enabled. By looking at the change history of this file the timeline of the development stages can be retrieved easily. Examples for AppVersion are: 1.7-a1, 1.7.3-b2, 1.7-rc1, 1.7

The development stage letters have the following meaning:

a - alpha: not feature complete, internal testing

b - beta: feature complete, ready for external testing

rc - release candidate

no DevelopmentStage - means final release, in this case there is no build number in the file name.

The stage numbers always start at 1 and are only incremented in case of stepping back to a previous development stage. The order of development stages is a then b then rc then final. Thus, when for example '1.7-b1' turns out to have missing features or other severe problems, development is set back to '1.7-a2', later followed by '1.7-b2' and '1.7-rc1', etc.

The build machine maintains a sequential build number for every build performed. This information is not under Git version control but local to the build machine.

The generated BlackBox.exe file also carries version information. See 'Properties' of this file under the Windows Explorer. The version information here consists of four version numbers: MajorVersion.MinorVersion.PatchLevel.BuildNumber, where PatchLevel defaults to 0 if missing in AppVersion.

The build machine derives all required version information from 'AppVersion.txt' and from the internally maintained build number. There is only one single place in the source code repository that needs to be changed in order to express a switch from one development stage to another.