Skip to content

Commit 7afbe70

Browse files
wenzeslauswenzeslaus
authored
RFC: Version Numbering (#2357)
This PR is a RFC for a new version numbering system. The main point is not making any distinction between even and odd version numbers. After 8.2, 8.3 would follow.
1 parent 3e0c87a commit 7afbe70

File tree

3 files changed

+251
-35
lines changed

3 files changed

+251
-35
lines changed

‎doc/development/rfc/version_numbering.md

+241
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# RFC: Version Numbering
2+
3+
Author: Vaclav Petras
4+
5+
Status: Draft
6+
7+
## Summary
8+
9+
Use version number in a format _major.minor.micro_ where
10+
11+
- _major_ is for large additions or backwards incompatible changes,
12+
- _minor_ is for additions, and
13+
- _micro_ is for fixes.
14+
15+
These numbers are assigned to releases. Development versions, pre-release,
16+
and builds are marked by additional labels as suffixes.
17+
18+
Once a version number is assigned to a release, the associated source code
19+
cannot change, or in other words, version number is assigned to a particular
20+
state of the source code. This is sometimes called a hard freeze (or code
21+
freeze). Unlike soft freeze (or feature freeze) and branching, code freeze
22+
does not allow any changes of the code.
23+
24+
All major and minor version numbers are used for releases,
25+
i.e., there is no distinction between even and odd numbers.
26+
27+
## Background
28+
29+
The increasing versions were always following the same ideas as in
30+
the [Semantic Versioning](https://semver.org/),
31+
i.e., _major_, _minor_, and _patch_,
32+
with major for breaking changes, minor for backwards compatible
33+
features, and patch for fixes.
34+
35+
For the versions 7.0 till 8.2, there was a distinction between even
36+
and odd minor versions.
37+
Even minor versions were released, while odd minor versions marked development versions.
38+
These odd versions never had a patch number assigned and were never released.
39+
40+
The practice of odd minor versions denoting development versions and even minor versions
41+
denoting releases was introduced with 5.0.0 and was followed in various ways in the
42+
version 5 and 6 series.
43+
This odd-even practice followed the numbering scheme of the Linux kernel
44+
which abandoned the practice since then.
45+
46+
At the time of version 5, the odd-even practice replaced a system where multiple
47+
numbered beta versions were released. Version 5.0beta10 was the last beta
48+
release before the first pre-release of 5.0.0.
49+
50+
The beta version practice was shortly picked up again for 7.0.0 which had four
51+
beta releases before the first release candidate of 7.0.0.
52+
53+
## Motivation
54+
55+
Explaining the version numbering should be as easy as possible.
56+
Ideally, it would not need any explanation at all.
57+
When all version numbers refer to releases, previews (alphas, betas, daily builds)
58+
always need additional indication of the version being a preview.
59+
However, using odd versions to mark the development versions still requires
60+
additional explanation, for example, download for 8.1 on the website
61+
said _preview_ anyway because the odd number does not indicate a
62+
development version by itself, i.e., it's not self-explanatory.
63+
Hence, odd numbers for development versions do not bring any advantage.
64+
65+
The branching and release procedure with even minor numbers for releases
66+
and odd numbers for development versions require that when a new branch for
67+
a minor version is created, the branch needs to change all the mentions
68+
of the minor version number to the next even number and, at the same time,
69+
the _main_ branch needs to change to the next odd number.
70+
Without the even and odd distinction, the branch keeps the version from
71+
the main branch while the main branch advances to the next upcoming version
72+
resulting only in one operation.
73+
74+
The Semantic Versioning uses labels after the version number to indicate development
75+
versions, so using that system or a similar one should be sufficient to mark the
76+
development versions.
77+
78+
## Version Numbering Specification
79+
80+
### Format
81+
82+
Major, minor, and micro versions are separated by periods (dots),
83+
i.e., _major.minor.micro_. The format for development versions and
84+
build information is described in their respective sections.
85+
86+
### Major
87+
88+
In accordance with Semantic Versioning, a major release must happen with
89+
any backwards incompatible change in the API which includes
90+
both interface and behavior changes (API also defines what happens,
91+
not just names and signatures).
92+
93+
Additionally, major feature additions which would require only a minor release
94+
in terms of API stability, are strongly suggested to trigger a major release
95+
as well. This in turn helps to address the issue of outdated tutorials and
96+
small, but breaking, changes.
97+
98+
Some major features, such as changes in the GUI, are fully backwards compatible
99+
(GUI API is not a public API in versions 7 and 8), but major features may
100+
heavily influence tutorials and other teaching materials. In that case,
101+
increasing a major version should be considered given that,
102+
in a sense, behavior linked to a particular interface is changed.
103+
104+
There is always a list of many small changes which are not backwards compatible,
105+
for example, a cleanup of deprecated functions. None of these changes alone
106+
seems worth a major release, but because it would require one, it is never done.
107+
With more common major releases, small changes can happen more often.
108+
109+
### Minor
110+
111+
Minor version must be incremented if new functionality is added
112+
or if existing functionality is marked as deprecated.
113+
Minor version increment is strongly recommended for all new functionality or improvements
114+
which are not bug fixes.
115+
116+
### Micro
117+
118+
If only backwards compatible bug fixes, i.e., fixes of incorrect behavior, are applied,
119+
a micro version can be released.
120+
121+
The micro version is also known as _patch_ (which is what Semantic Versioning
122+
is using) and _point_ (which is what was used in some GRASS GIS documents).
123+
The word _micro_, rather than patch, is used
124+
to avoid collision with patch referring to an individual changeset or fix
125+
(a release contains one or more of these changes).
126+
A point release (or a _dot_ release) can generally apply to anything after
127+
the first dot, i.e., minor or micro release, while
128+
using minor and micro does not have that ambiguity.
129+
Although minor and micro have potential for confusion due to the
130+
similarity of their names, minor is an established term in this context
131+
and micro is sometimes used in this context and in other contexts
132+
(e.g., micro donations), so it has the right connotations.
133+
134+
### Development Versions
135+
136+
Development versions have the version number of the next release which will be released
137+
from a given code base which is defined by a branch.
138+
139+
Development versions of source code on each branch have a dev suffix,
140+
e.g., 3.5.1-dev.
141+
Transition to the Semantic Versioning style is strongly recommended
142+
which means including dash (hyphen) before dev, e.g., 3.5.1-dev.
143+
Notably, these dev-suffixed version numbers are not unique, i.e.,
144+
multiple source code versions are marked the same.
145+
146+
Release candidates (RCs) are pre-releases marked by appending RC and
147+
a release candidate number to the version, e.g., 3.5.1RC2.
148+
149+
Transition to the Semantic Versioning style for pre-releases is strongly recommended.
150+
Version number is followed by a dash (hyphen) followed by a dot-separated identifier
151+
which consists of identification of pre-release type, i.e., rc or RC, optional dot,
152+
and a release candidate number, e.g., 3.5.1-rc.2, 3.5.1-RC.2, 3.5.1-rc2, or 3.5.1-RC2.
153+
154+
Daily builds and other builds of development versions other than release candidates
155+
may use additional dashes to specify the actual source version, e.g.,
156+
3.5.1-dev-05e5df2e7, or day, e.g., 3.5.1-dev-2023-05-29.
157+
158+
Any version parsing or build system must support both systems, the one without
159+
a dash and the one with a dash.
160+
161+
### Build Information
162+
163+
When build information is captured in the version number, Semantic Versioning
164+
prescribes a plus sign as a separator, e.g., 3.5.1+1 or 3.5.1-RC1+1.
165+
However, filenames with a plus sign may not work well, so a dash as a separator
166+
is allowed too while keeping in mind that automated semantic version tools
167+
won't parse the version correctly. A suggested workaround is to use the dash
168+
only in a file name and use plus sign everywhere else.
169+
170+
Any version parsing or build system must support the form with a dash
171+
and the form with a plus sign.
172+
173+
While the assignment of a version is typically done by tagging in a version
174+
control system, so the assumption is that there is always a related tag,
175+
the builds are managed separately, so the assumption is there is no tag in
176+
the version control system.
177+
178+
## Usage
179+
180+
Version numbers should be presented in their specified format.
181+
When appropriate, a shorter version can be used, for example 4
182+
to refer to the whole series or 4.3 to refer to the latest releases
183+
(regardless of the current micro version).
184+
185+
Leaving out the periods (dots) from the version numbers and combining
186+
major, minor, and micro into a single number is discouraged because of
187+
the lack of clarity for humans and because of the
188+
ambiguity for parsing (35 can be version 3.5 or 35).
189+
190+
Version should be considered a separate item from the name.
191+
The name of the project and software is GRASS GIS, not GRASS GIS 8.
192+
So, don't use "GRASS GIS 8 includes foo and bar" when you simply mean
193+
"the current version includes foo and bar" or "GRASS GIS includes foo and bar".
194+
195+
In documentation, the version is often really needed, but don't say
196+
"the default database driver in GRASS GIS 7 is SQLite", instead say
197+
"the default database driver in GRASS GIS is SQLite (since version 7)."
198+
This way the version number in the sentence will always be valid because
199+
the version when the change was introduced stays the same and does not change.
200+
201+
When a version is part of an output or displayed to the user, the version
202+
number should be determined dynamically, not hardcoded, even if it is just
203+
the major version number.
204+
205+
Don't include the version number where it is not needed, for example, text for links
206+
in a release announcement doesn't need a version because version is already given
207+
by the context.
208+
209+
In short comments, references using GN where N is major version number are not
210+
common in general. When the version is important to mention, use vN which is
211+
a common practice.
212+
213+
## Relation to Other Documents
214+
215+
- [RFC 4: Release Procedure](https://trac.osgeo.org/grass/wiki/RFC/4_ReleaseProcedure):
216+
This RFC describes changes to the numbering. RFC 4 describes the release procedure.
217+
- [Release Schedule](https://trac.osgeo.org/grass/wiki/Release/Schedule)
218+
(at Trac wiki under Release): The Release Schedule document describes
219+
schedule, branching, release maintenance, and numbering. The numbering is
220+
changed, specifically the use of odd version numbers for development.
221+
- [Semantic Versioning](https://semver.org/) (version 2.0.0 at the time of
222+
writing): Semantic Versioning treatment of _major_, _minor_, and _micro_
223+
numbers should be respected. The labeling of other versions does not comply
224+
with Semantic Versioning, but it is a desired state for the future.
225+
226+
## Other Projects
227+
228+
GDAL and PROJ follow the Semantic versioning. QGIS does as well, but in
229+
combination with odd numbers marking the development versions.
230+
231+
Ubuntu and Black lock their version numbering with the release schedule.
232+
Black, after transitioning from beta, releases a major release yearly in January
233+
using the last two digits of year as major version and month as minor release.
234+
235+
## Historical Documents
236+
237+
- Glynn Clements (2007). GRASS-dev GRASS 6.3.0 release preparation.
238+
Aug. 12 18:12:32 EDT 2007. <https://lists.osgeo.org/pipermail/grass-dev/2007-August/032705.html>
239+
- Neteler, Markus (2001). Towards a stable open source GIS: Status and future
240+
directions in GRASS development. Second Italian GRASS Users Meeting,
241+
University of Trento, Feb. 1-2 2001. <https://www.academia.edu/download/5140572/10.1.1.16.8991.pdf>

‎utils/update_version.md

+8-17
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Updating Version File
22

3-
Version file (`include/VERSION`) can be updated using the _update_version.md_ script.
3+
Version file (`include/VERSION`) can be updated using the _update_version.py_ script.
44

55
The script captures the logic of updating the version file incorporating
66
the common actions and workflow checks.
@@ -54,20 +54,22 @@ echo $VERSION
5454

5555
### Updating Minor Version
5656

57-
Let's say we are at development-only version 3.1.dev and just created
57+
Let's say we are at the main branch, version 3.2.0dev, and just created
5858
a new branch for 3.2 release, so we want to update the minor version
59-
to the next minor version:
59+
on the main branch to the next minor version:
6060

6161
```sh
6262
./utils/update_version.py minor
6363
```
6464

6565
Separately, or as part of other changes, now is the time to commit,
66-
so the script suggests a commit message:
66+
so the script suggests a commit message in the output, e.g.:
6767

6868
```yaml
69-
message: Use the provided title as a commit message
70-
title: 'version: Start 3.2.0dev'
69+
read:
70+
user_message: Use the provided message for the commit
71+
use:
72+
commit_message: 'version: Start 3.2.0dev'
7173
```
7274
7375
### Error Handling
@@ -86,14 +88,3 @@ only after the release:
8688
```text
8789
Already dev with micro '0dev'. Release first before update.
8890
```
89-
90-
### Updating Development-only Version
91-
92-
Development-only versions have odd minor version numbers and are never actually
93-
released. Given the branching model, all these versions are on the _main_ branch,
94-
so there the minor version is increased by two. This can be done by running
95-
the _minor_ command twice or by using the `minor --dev`:
96-
97-
```sh
98-
./utils/update_version.py minor --dev
99-
```

‎utils/update_version.py

+2-18
Original file line numberDiff line numberDiff line change
@@ -143,22 +143,9 @@ def update_minor(args):
143143
version_file = read_version_file()
144144
micro = version_file.micro
145145
minor = int(version_file.minor)
146-
if args.dev:
147-
if not minor % 2:
148-
sys.exit(
149-
"Updating to a development-only version "
150-
f"from an even minor version '{minor}' is not possible"
151-
)
152-
minor += 2
153-
else:
154-
minor += 1
146+
minor += 1
155147
if micro.endswith("dev"):
156-
if minor % 2:
157-
# Odd is development-only, never released and without micro version.
158-
micro = "dev"
159-
else:
160-
# Even will be released, so adding micro version.
161-
micro = "0dev"
148+
micro = "0dev"
162149
else:
163150
sys.exit("Updating version from a non-dev VERSION file is not possible")
164151
write_version_file(
@@ -283,9 +270,6 @@ def main():
283270
subparser = subparsers.add_parser(
284271
"minor", help="increase minor (x.Y.z) version (uses dev in micro)"
285272
)
286-
subparser.add_argument(
287-
"--dev", action="store_true", help="increase development-only version"
288-
)
289273
subparser.set_defaults(func=update_minor)
290274

291275
subparser = subparsers.add_parser(

0 commit comments

Comments
 (0)