Skip to main content

Version 2

Vectors​

Vectors are integers or strings, which can only contain one piece of information. This specification specifies five distinct vectors.

Release​

The release vector is an integer and starts at 1.

It keeps track of major changes within an application, document or other work. Major changes require a version vector bump. For example, breaking changes require a version vector bump.

A release vector bump is required, when:

  • a breaking change is introduced
  • the public, exported API changes (for applications)

The release vector may stay at 1 during the initial development, but should be increased once the work is usable and in a good state. Works and especially applications should not stay on one version indefinitely.

Type​

The type vector is a string and must have one of four values: alpha, beta, releasecandidate or release.

This vector identifies how stable the released version is.

  • alpha identifies the work as experimental. The work may have many unresolved issues and may change significantly during further development. Usage is not recommended.
  • beta identifies the work as unstable. The work may have a few unresolved issues and may change from time to time during further development. Usage is not recommended.
  • releasecandidate identifies the work as potentially stable. The work may have a few smaller issues but it's shape is final. No new features may be added anymore unless required. Usage only recommended for testers and early birds.
  • release identifies the work as tested and stable. The work is finished and can be used without any problems.

Typerelease​

The typerelease vector is an integer and starts at 0.

It keeps track of how many times a specific version type has been released. It resets back to 0 when the release or type vectors change.

Fork​

The fork vector is a string, can have any value (except for dashes and plus signs) and can be unset.

It identifies a fork of some other work.

Example: Plate gets forked and it's fork is named Bowl. Bowl's fork vector will then be set to bowl (which was previously unset) to identify that Bowl is a fork of Plate with a few modifications.

Companion​

The companion vector is a string, can have any value and can be unset.

This vector identifies the version of another work that the work is based on.

Example: Modification Improved Metal (which uses this versioning specification) modifies Spoon (which uses SemVer) version 4.1.2. The companion vector of Improved Metal will then be set to 4.1.2.

Format​

A format is required for vectors to be displayed in. The release, type and typerelease vectors are required, the companion and fork vectors aren't. To leave one of the optional vectors out, simply remove the vector in question and it's separator character in front of it.

Minimal vectors​

v23-releasecandidate5
 ^  ^               ^
 |  |               |
 |  |               ------------ Typerelease vector
 |  --------------------------- Type vector
 ----------------------------- Release vector

All vectors​

v23-releasecandidate5-somefork+2.5.1
 ^  ^               ^ ^        ^
 |  |               | |        |
 |  |               | |        --- Companion vector
 |  |               | ----------- Fork vector
 |  |               ------------ Typerelease vector
 |  --------------------------- Type vector
 ----------------------------- Release vector

SemVer Compatibility​

One of this specifications goals is to be compatible with the semantic versioning system 2.0.0. To achieve this, simply use this format instead:

23.2.5-somefork+2.5.1
^  ^ ^ ^        ^
|  | | |        |
|  | | |        ----- Companion vector (build)
|  | | ------------- Fork vector (pre-release)
|  | -------------- Typerelease vector (patch)
|  --------------- Type vector (minor); alpha is 0, beta is 1, releasecandidate is 2 and release is 3
----------------- Release vector (major)