Section 3.5. Labeling Builds

3.5. Labeling Builds

There are numerous places in a development environment where having a standard way of describing a build is useful. If you don't define a standard way, then the SCM tags for a build will be formatted one way, the build will appear in the bug tracking system in a different way, and the release names will be defined in yet a third way.

What information should be in a build label? My suggestions are:

Build type

Was this build for internal testing (QA) or release (REL)?

Version

The major, minor, and patch numbers; for example, 1_3_0. Section 9.2.3 has more details about different versioning schemes.

Build number

A number that uniquely identifies each build. Section 9.2.2 has more details about using build numbers.

Date

The year, month, and day when the build was started, in that order so that builds can be sorted on this field. If you plan to do more than one build per day, then the hour and minute from a standard time zone are useful too.

Special

If the build is otherwise significant, add an optional field at the end. An example is BETA for a beta release. Put this at the end of the label so that alphanumeric sorting of the label is not overly affected by it.

Each of these fields should be separated from the next with a character such as #, -, or _ so that the label can be parsed by shell scripts and other programs. If the # character is used with the above label format, then the label for internal build 129 of Version 1.3.0 of a product on July 9, 2005 would look like:

QA#1_3_0#129#2005_07_09

Another requirement for a build label is that it should not contain characters that are illegal in any of the contexts that the label will be used inthat is, SCM labels, file and directory names, field values in your bug tracking system, web pages, and documentation. Characters to avoid include $, <, >, |, /, \, spaces, and tabs. Underscores don't show up in underlined links on web pages. Some SCM tools have their own restrictions as well.

Build labels don't need to have a branch name in them, since the version number and build number can tell you whether a branch was used for the source code. Embedding the name of a branch point in a build label also seems like overkill, since this can be recorded elsewhere, along with rest of the information about the purpose of the branch.

Once a build label format has been chosen and agreed on, document it and post it in a public place. Consider very carefully any requests to change it, since its details will have been embedded in numerous tools and filenames.