86 lines
4.1 KiB
Markdown
86 lines
4.1 KiB
Markdown
|
---
|
||
|
|
sidebar_position: 2
|
||
|
|
title: "2"
|
||
|
|
description: "Versioning Specification v2"
|
||
|
|
---
|
||
|
|
|
||
|
|
# 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](https://github.com/gohugoio/hugo/releases).
|
||
|
|
### 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 earlybirds.
|
||
|
|
- **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](https://semver.org)) 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
|
||
|
|
```plain
|
||
|
|
v23-releasecandidate5
|
||
|
|
^ ^ ^
|
||
|
|
| | |
|
||
|
|
| | ------------ Typerelease vector
|
||
|
|
| --------------------------- Type vector
|
||
|
|
----------------------------- Release vector
|
||
|
|
```
|
||
|
|
### All vectors
|
||
|
|
```plain
|
||
|
|
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](https://semver.org) 2.0.0. To achieve this, simply use this format instead:
|
||
|
|
```plain
|
||
|
|
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)
|
||
|
|
```
|