Versioning
FleCSI uses the Semantic Versioning system. Note that it defines the three kinds of releases in terms of restrictions on what changes can appear in each, and that those restrictions are phrased in terms of the documented interface. We interpret compatibility strictly in terms of source (with the inevitable judgment calls for things like SFINAE). Even altogether new code can appear in a “patch” release if it serves to fix a bug or improve performance rather than as a new documented feature. As an exception to the specification, deprecations can be made in such a release as well, since they are merely documentation for the careful user who wants to upgrade early for forward compatibility. However, since features are typically deprecated in favor of some new feature, most will nonetheless appear in feature releases.
There is one active, shared branch for each of the three types of release, as described below. Tags are used to identify releases as well as certain internal reference points for development.
Branch Types
- incompatible
The develop branch is where work on the next major release takes place, potentially with interface and feature changes that are incompatible with previous versions.
- feature
Feature branches (named for their major version number, e.g., 1, 2, 3) are for feature development on the current major version.
- release
Release branches (named for their major.minor version number, e.g., 1.1, 1.2) are interface-stable versions of the code base. At appropriate points, tags (named for their major.minor.patch version number, e.g., 1.1.2) are used to identify patched versions.
Fig. 26 Workflow diagram illustrating basic workflow using the three branch types described above. (Figure due to Angela Herring.)
In general, each change should be made on the most restrictive permissible relevant branch so as to minimize divergence between them (after merging) and the associated potential for future merge conflicts. The condition of relevance pertains to an internal feature that might be added only on the feature branch if it is not expected to accrue any clients on the release branch. A sometimes countervailing consideration is stability: users expect that patch releases are less likely to cause problems when upgrading even though it is simply a bug if even a feature release does so. It is also unfortunate to need to consider reverting a change because an official release is needed in the interval between introducing it and becoming confident in it.
FleCSI Version File (.version) and FLECSI_VERSION
The contents of the .version file in the root of a FleCSI source
checkout is used to identify the branch type and version of
FleCSI. Given the three different branch types and tagged versioned
releases, its content will be one of the following four schemes:
- develop branch
develop- feature branch
f<major>- release branch
r<major>.<minor>- tagged release
v<major>.<minor>.<patch>
FleCSI uses the information in .version to define
FLECSI_VERSION in its flecsi/config.hh header. This constant
encodes the major, minor and patch version of FleCSI in a single
integer value.
For tagged releases (v<major>.<minor>.<patch>) it is defined
as (major << 16) | (minor << 8) | patch.
On release branches both major and minor version components are set to the release version, however, the patch version component is set to its maximal value 255.
On feature branches only the major version component is set to the version value, while the minor version component is set to its maximum 255 and the patch version component is set to 0.
Finally, on the develop branch, the major version component is set to its maximum 255, while the other components are set to 0.
The following table summarizes these rules with some examples:
Source |
Contents of |
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|