-
Notifications
You must be signed in to change notification settings - Fork 1
Version Numbering Strategy
The purpose of this document is to provide an explanation of, and authoritative reference for, the version numbering strategy for all FabMo products, which at the time of this writing, includes the FabMo Engine and the FabMo Updater.
Software packages in the FabMo ecosystem are broken up into development (dev) ,release candidate (rc) and release (rel) packages. Packages of all types are meant to be installable alongside one another, but the process and lifecycle of each type of package may be different.
A development package is built from a snapshot of code that is currently in development. This is sometimes called a "nightly" and although we may decide to build it nightly, we will reserve the term "nightly" builds for builds that are actually done overnight. A dev package is a snapshot, not attached to a specific release.
The version number of a development package takes the form: v1.2.3-Xabcdef!-dev where v1.2.3 is the closest released ancestor to the software package. X is an alphanumeric indicator of the SCM being used, which will (for now) always be the letter g (for git). abcdef is the SHA1 hash of the commit that represents the snapshot. This uniquely identifies the entire software package, and can be looked up in the SCM software as needed. We're avoiding doing more descriptive things here (for instance indicating the branch or making further use of tags) because these things are almost always 1) ephemeral (tags can be deleted, branches can be pruned) and 2) not as completely descriptive as the commit hash. For more information about the use of tags and hashes here, see https://git-scm.com/docs/git-describe Finally, the exclamation point in the hash is optional. It's presence indicates a "dirty" snapshot - that is one that contains local code modifications. Ideally even development snapshots never have this designation, but because the SCM tools can provide that indication, it is a safeguard of the code integrity to indicate it, when the information is available.
A release candidate is also built from a snapshot of code that is currently in development. It is in mostly the same as a development package, except that a release candidate package uses the version number for the upcoming release, rather than the most recently released ancestor. Release candidate packages have a version number of the form v1.2.4-[x]abcdef-rc with the hash and SCM identity having the same meaning as described above in the development packages section.
Release packages are the simplest type of releases. They correspond directly to an annotated tag (in git) and have a version number of the form v1.2.3 in which the numbers correspond to the major, minor and patch release numbers respectively. With released packages, there are fewer opportunities for irregularity, and because tags point directly to a commit hash, it is straightforward to point to the actual source code of the release given the version number, so long as the tag is intact. For this reason, it is best practice never to delete a tag that corresponds to a released version, or the link between a versioned release package and the source code that corresponds to it will be lost.
-
v1.2.3- Major release 1, minor release 2, patch release 3. RELEASED code. -
v1.2.3-ga1bb679-dev- Development snapshot @ commit a1bb679 - most recent release was v1.2.3 -
v1.2.4-ga1bb679-rc- Release candidate for version 1.2.4 - this is the same code as the development version - above, but will become v1.2.4 if the code is released.
-
v1.2.3-gbb1347a-dev- Development snapshot @ commit bb1347a - There is no way to know if this is on the same development branch, or is older or newer than the development version listed above, unless you go to the source repository, and compare the commits yourself. This might be seen as an encumberance, but has the advantage of being authoritative, at least.
A development or dev release is a type of release, whereas master is the name of a branch. A dev release can be built from the master, but it can also be built from any other branch. Our standard practice is to regularly build a development release from the master for the testing of cutting-edge features. If you've got a dev release on your tool, there's a good chance it's built from the master branch, but this isn't required, just our typical workflow. It may be that for the purposes of testing a specific feature that is being developed in a branch, a dev release might be built from that branch instead, although this doesn't happen frequently. If you're on a development release and you ever want to know where the source code came from, though, there's good news: You can always use the commit hash to look it up on github.