1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
= Versioning
OpenSCAP release versions have the common *$major.$minor.$patch* format.
Most of the bleeding edge unstable development happens in the *main* branch.
This branch is likely to break API and ABI and is likely not suitable for anyone
but the developers. Only release candidates or other test releases are tagged
from the main branch.
*$major.$minor* together (e.g.: `1.2`) are called *feature releases*. As the
name suggests, once a feature release is made, no new features are added to it.
For example once `1.2.0` is released, `1.2.1`, `1.2.2`, `1.2.3`, etc. shall not
have more features than `1.2.0`. Patch version 0 (e.g.: `1.2.0`) establishes
the feature set.
Feature releases form a maintenance branch that we call *maint-$major.$minor*.
For example the maintenance branch for `1.2.x` is called `maint-1.2` in the git
repository. This means that all releases with version `1.2.x` shall be tagged
from the `maint-1.2` branch.
Releases from the same maintenance branch are called *sibling releases*.
== Maintenance branch rules
Library users tend to use released versions, because that is the only sure way
to avoid rebuilds, breakages and/or mysterious bugs caused by ABI
incompatibility. To make sure our released versions do not suffer from these we
maintain them in a separate branch and only allow commits that pass very strict
rules.
=== No API/ABI breaks!
Only changes that do not break API and ABI can be applied to the maintenance
branch. This is a non-negotiable rule! If a breaking change is applied
to a maintenance branch by mistake it has to be reverted. ABI checking should
be done before releases using abi-compliance-checker.
=== No changes to documented behavior
If a certain behavior of the library or tools is documented it cannot be changed
in the maintenance branch even if it is considered broken or wrong. Only changes
that make the implementation more compliant to documentation can be considered
- these changes are most commonly bugfixes.
Incompatible improvements shall always be done in the development (`main`)
branch if they are done at all. The commits should be accompanied with
appropriate changes in documentation.
Of course there is a gray area in this rule. In cases where the documentation
is vague and permits multiple interpretations we prefer to make the
documentation explicit and consistent with established behavior. In other
words: changing documentation is preferred to changing behavior.
=== Only careful changes of supporting files (XSD schemas, XSLT)
Only small non-invasive changes should be considered. Make sure old use-cases
aren't broken.
As an example the report XSLT may get a small usability improvement - it will
show number of notchecked rules along with all the other information. However
we may not remove or replace information from it in the maintenance branch
- users may be relying on it being there. Radically moving information around
in the report is also discouraged. It's very hard to lay formal rules
surrounding this so please use your best judgement.
=== All applied changes must be propagated
Bugfixes applied to maintenance branches must be merged up. For example,
a bugfix applied to `maint-1.2` shall be merged to `maint-1.x` (where `x > 2`)
which then shall be merged to `main`.
This rule makes sure we always carry bugfixes to new feature releases.
In cases where the bugfix does not make sense in newer feature releases, a noop
merge shall be done. For example, a fix for functionality that was removed in
a newer feature release.
== Frozen branches
Maintenance branches can be frozen which further restricts the changes that can
be applied to them. Only bugfixes are permitted in frozen branches.
== Maintenance status
* 1.3.x: supported
* 1.2.x: supported
* 1.1.x: unsupported since 2015-10-16
* 1.0.x: unsupported since 2017-06-01
== Feature release
A new feature release will typically contain new symbols and ABI breaking
changes in existing symbols, although this is not a rule. Therefore it will
likely but not necessarily have incompatible ABI (and thus different soname).
Deprecated symbols from feature release `N` shall be removed in feature release
`N + 1`. For example, deprecated symbols from `1.1.x` shall be removed from
`1.2.x`. In other words, deprecated symbols shall not be carried to the future
feature releases.
|
