-
Notifications
You must be signed in to change notification settings - Fork 2
Versioning guideline
This document is a proposal that describes the syntax of the version name of any kind of ESGF stack project.
X ; Y ; Z ; N are zero or positive integers v ; . ; a ; b ; rc are just symbols:
vX.Y aN syntax for alpha releases ^ ^ bN syntax for beta releases | | rcN syntax for release candidates | | .Z syntax for production/maintenance releases | | | |____ minor version | |____major version
X.Y.0 is the first production release of the X.Y version family. X.Y.Z where Z > 0, are maintenance releases of the X.Y version family.
Software versioning is a process that aims to assign unique identity tag to a unique state of a software or project. This process is very important as the actors of a software development can rely on these tags so as to debug, add new features, etc.
This document is a proposal, a guideline for versioning any kind of software/project.
At first, this document presents a simplified development/release cycle as a guiding thread for the versioning syntax. The last section gives some recommendations about the git workflow.
An example of release cycle (ascending order):
- untag/unreleased version of the project (but managed in a branch of a git repository)
- alpha releases (optional, at the developer's discretion, to be tested by friendly users)
- beta releases (optional, at the developer's discretion, can be tested by wider users)
- release candidates (rc)
- production releases (first production version followed by maintenance versions)
vX.Y.Z
X ; Y ; Z: zero or positive integer values (can take more than one character ; start from zero). v ; . are just symbols. ex: v2.5.0
Note: of course, we can add another level (we have just to describe the semantic of that level).
This value reflects the familly of the version - major version -
This value should be incremented only when the project is substantially upgraded. For example when:
- the backward compatibility is not supported with the second to last release
- the software architecture is refactored.
- core functionalities are refactored.
- etc.
This value reflects minor changes within the same version family - minor version - This value should be incremented when the modifications of the project are between maintenance patches and deep modifications. Typically when:
- adding a new feature
- substantial ui modifications
- substantial installation procedure modifications
- substantial bug fix
- etc.
This value reflects a batch of bug fixes or cosmetic modifications. In fact, these little modifications should have been implemented at the release candidate step... but they have been discovered afterward.
X.Y.0 is the first production release of the X.Y version family. X.Y.Z where Z > 0, are maintenance releases of the X.Y version family (successors of the X.Y.0)
Maintenance release (X.Y.Z) can skip alpha/beta or rc versions (e.g. 2.5.10rc9) : maintenance releases are just production release with lightweight modifications or simple bug fixes. However if an important bug has been discovered, the development team should start a new release cycle: increment the Y number and release (alpha/beta and) rc versions of the project.
Alpha and beta releases are usually for development purposes. They are hardly ever distributed to end users. These versions are associated to the version currently in development.
- Alpha syntax: vX.YaN where X ; Y are like the syntax of the production release and N is also a zero or positive integer that refers to a specific alpha version.
- Beta syntax: vX.YbN where X ; Y ; N like alpha version but refers to a specific beta version.
v ; . ; b ; a are just symbols.
Examples: v2.5a10 and v2.5b9 are, respectively, an alpha and an beta version of the version v2.5 currently being in development.
Release candidates (RC) are versions of the project for real world testing. They are distributed to users so as to get feedback and fix the last bugs, adjust user experience, etc. right before the release of the production version. When the production release comes out, we must stop to distribute the release candidates.
RC syntax: vX.YrcN , where X ; Y are like the syntax of the production release and N is also a zero or positive integer that refers to a specific release candidate.
v ; . ; rc are just symbols.
Example: v2.5rc9 is a release candidate of the version v2.5 currently being in development.
- vX.Y.aN|bN|rcN (e.g. v2.5.rc9): a dot symbol should not be placed between minor version and development version tag. Development versions are associated to a X.Y family. They are not a subfamily on their own.
- v2.5rc09 : Zeros should not be added, the number of characters of X, Y, Z and N is not specified.
- v2.5.9-master : Git branch information should also not be indicated, since v2.5.9 is enough to describe that this version is the maintenance version 9 of the 2.5 family.
The latest development versions (alpha, beta or rc) are usually production releases. They normally refer to the same state of the project. So the transition from the last development version to the production version is pretty simple: create the git tag of the production release from the same set of source files of the last development version.
For example if v2.5rc10 is the version to be used as the first production version (v2.5.0) of the v2.5 family. So v2.5rc10 and v2.5.0 refer to the same code of a git repository.