-
Notifications
You must be signed in to change notification settings - Fork 0
Versioning and Repository Management
The primary goal of the version number is to precisely identify what feature set a particular version have or what API specification it intends to follow from multiple point of view.
Using the Semantic Versioning requires strict conduct on the programmer side for Semantic Versioning to properly work and convey the relationship between releases as intended. This page discusses how is the Semantic Versioning is utilized in this project as well as proposes a way to manage a product using Semantic Versioning and managing repository. These rules are applied when managing this project but as a proposal any part of it can be adapted as appropriate.
Note: After thorough consideration, the version “1.0.0-alpha+10.7” release should be considered to be version “0.0.0-0+2ce89229ec.7.Win23NT” as it is now clear that the version in question is a pre-1.0 version and should not be assumed to be a final API. When the project reaches 1.0.0 version, it will skip this version number immediately to 1.0.0-alpha.1 according to the guide specified below.
Since there is one-to-one match between .NET's assembly versioning and Semantic Versioning the following numbers are defined as follow:
- Build number: Indicates the number of build this release come from. This is an arbitrary number that always greater for a release than previous releases.
- Revision number: Depending on the context, it is either a string representation representing the revision/commit number or a numerical value referring to the nth revision from the initial commit, either by counting a certain set of commits or provided by the version manager.
When specifying a semantic version as a version in .NET, the Major, Minor are used in the Major and Minor fields, an the Build and Revision numbers take the value from the Build number and Revision number specified above.
Following these rules in a public build a version could look like this:
- Semantic Version: 1.5.0-beta.8+6.102.Win32NT
- Equivalent Version number: 1.5.6.102
When a public release is to be made a build procedure must specify the following environment values:
| Variable | Purpose |
|---|---|
| BUILD_NUMBER | The nth build that is about to be executed |
| GIT_COMMIT | The GIT commit number the build procedure will work with |
| REVISION_NUMBER | The numerical representation of a revision number |
| SPECIAL_BUILD | Optional string value specifying how this build deviates from the regular course of development- |
If BUILD_NUMBER or REVISION_NUMBER is missing, the build is considered to be a private build. If a build is a private build, the currently logged-in user name and machine name will be used instead of the build number and revision/commit number. When the variables are specified, all text-template must be converted to create the version number information for each project. The SPECIAL_BUILD environment variable is optional.
When building a private build, the environment variables are not needed to be specified; only the text templates are needed to be updated. A build is considered to be private, if it is not intended to be published here as a release of this project.
The build-metadata can have two sets of values depending whether it is a public build or a private build:
| № | Public build | Private build |
|---|---|---|
| 1st | BUILD_NUMBER | User name |
| 2nd | GIT_COMMIT | Machine name |
| 3rd | OS Platform | OS Platform |
| 4th | SPECIAL_BUILD | SPECIAL_BUILD |
When a prerelease is made, the following rule is followed:
The first component can be the following values for this project:
| Value | Meaning |
|---|---|
| Any number | A pre-alpha release |
alpha |
An alpha release |
beta |
A beta release |
release-candidate or rc
|
A release candidate version |
The life cycle of this project will always follow the following order:
number → alpha → beta → release-candidate.
It is possible that a project skips some of these stages.
The second component is a number which is used if another version is released with the same stage specified by the first component. This number is incremented whenever a new release is published with the same version and same value for the first component. This value is reset to 0 when the first component moves to the next stage. The value 0 is omitted.
The third component specifies what OS platform the build was compiled on. This can help determine what set of libraries were available during a build eliminating possible alternatives. For example, XNA Game Studio libraries only available on a windows platform, however on a Mac OS X, this only can be it's alternative; Mono Games. Another example is WPF, where the library Microsoft bundle with .NET only available on a Windows platform, however there exists an alternative for other platforms. The possible values are one of the System.PlatformID Enum values.
Note: The OS platform does not refer to the CPU architecture, regardless of it's value.
The file and product versions are versioned differently. When a file is updated, both it's product version and file version will be updated. But when there is no change in the file, the file version remains the same.
This project will fill it's version fields as follow:
| Field | Value |
|---|---|
| Assembly version | Major.Minor.0.0 |
| Informational Assembly version | Full semantic version |
| File version | File-Major.File-Minor.Build.Revision |
| Product version | Full semantic version |
The master branch should contain an ever changing code, that can transform independently of previous commits, and can be used to produce any number of private builds from it's source. When a public release must be made, the master branch must be tagged, which also fixates the released public API and steps in to the release cycle and is managed as a separate branch.
New features can be added to releases as “experimental versions” and should be noted with the SPECIAL_BUILD environment variable. These version will tag and branches off from tagged/branched release versions. Such experimental version should be treated separately from public API releases, not requiring the Major version number to be increased when the experimental feature is removed.
Thus if upper management (not for this project) request a feature immediately, it can be introduced as experimental feature so when it is later removed, it will only costs the minor version bumped one extra time in the master branch to accommodate the special build version.