1  # Versioning
 2  
 3  This document describes the versioning scheme used by the Radicle Stack, ie.
 4  the package that includes the Radicle CLI (`rad`), Radicle Node
 5  (`radicle-node`) and other binaries. It is not relevant to the Rust *crate*
 6  versions which follow [Semantic Versioning][semver].
 7  
 8  [semver]: https://semver.org/
 9  
10  ## Format
11  
12  Versioning of the Radicle Stack is based on Git tags. During the build phase,
13  we search for the most recent tag that starts with a `v` character, eg.
14  `v1.0.0`, and use that as the basis for computing the version.
15  
16  If we're building code that is pointed to by that tag directly, that code will
17  inherit that version number, with the `v` character stripped. For example:
18  
19      1.0.0
20  
21  If on the other hand, the commit we are building has no version tag pointing to
22  it, the output of `git describe` is used as-is. This indicates a development
23  version that is not released and not meant to be packaged or distributed. For
24  example:
25  
26      1.0.0-6-ga3ffe51d
27  
28  Tags used for versioning are always annotated and signed, and follow the format:
29  
30      "v" <major> "." <minor> "." <patch>
31  
32  When the tag is parsed, we strip the `v` prefix, which results in a version
33  matching:
34  
35      <major> "." <minor> "." <patch>
36  
37  For pre-releases or release candidates, we add the `-rc` suffix, plus a number.
38  For example:
39  
40      1.0.0-rc.2
41  
42  These releases are meant to be packaged.
43  
44  ## Semantics
45  
46  The Radicle version numbers do not follow strict rules, but these are the
47  guidelines we use:
48  
49  1. Increment the `<major>` number when significant changes and/or improvements
50     are made to the Radicle Stack. This should happen rarely.
51  2. Increment the `<minor>` number when new features are added or existing
52     features are improved in a noticeable way.
53  3. Increment the `<patch>` number when bugs are fixed, docs are updated or
54     features are tweaked.
55  
56  Unless clearly stated in the documentation, none of the user-facing commands
57  should be considered stable APIs, and may therefore break in `<minor>` or
58  `<major>` version updates. If command output is considered stable, and an
59  effort is made to maintain that stability, this will be stated in the command's
60  documentation.