Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-01-11 15:29:41 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update "version scheme"

Browse Source 
- Add info about major, minor, and patch releases
- Add info about common abbreviations
- Add links
- Improve language
- Improve formatting
- Fix typos
- Convert table from HTML to Markdown
This commit is contained in:
Andrew David Wong 2021-09-06 22:49:07 -07:00
parent 2774c83a98
commit dbb3c3c4ac
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 79 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
developer/releases/version-scheme.md
View File

@ -14,6 +14,14 @@ The Qubes OS Project uses the [semantic versioning](https://semver.org/)
standard. Version numbers are written as `<major>.<minor>.<patch>`. When standard. Version numbers are written as `<major>.<minor>.<patch>`. When
`<patch>` is zero, it is often omitted as a matter of convention, e.g., `4.1`. `<patch>` is zero, it is often omitted as a matter of convention, e.g., `4.1`.
In general, patch releases are for backward-compatible bug fixes, minor
releases are for backward-compatible enhancements and new features, and major
release are for any backward-incompatible changes. This means that, in general,
one should *not* try to introduce features or enhancements in patch releases or
any backward-incompatible changes in patch or minor releases. Bug fixes are
allowed in all releases, and backward-compatible changes are allowed in all
major and minor releases.
Following standard practice, **version** refers to any build that has been Following standard practice, **version** refers to any build that has been
assigned a version name or number, e.g., `3.2-rc2`, `4.0.4`, `4.1-beta1`. By assigned a version name or number, e.g., `3.2-rc2`, `4.0.4`, `4.1-beta1`. By
contrast, **release** refers to any version that is intended for consumption by contrast, **release** refers to any version that is intended for consumption by
@ -23,51 +31,55 @@ the general userbase. For example, `4.0.4` was both a **version** and a
and was intended only for [testing](/doc/testing/). All **releases** are and was intended only for [testing](/doc/testing/). All **releases** are
**versions**, but not all **versions** are **releases**. **versions**, but not all **versions** are **releases**.
Qubes distributions and products The letter **R**, as in `R4.1` stands for **release**. The abbreviation **RC**,
-------------------------------- as in `3.2-rc2` stands for **release candidate**.
## Qubes distributions and products
We intend to make it easy to make a remix of Qubes, targeting another We intend to make it easy to make a remix of Qubes, targeting another
hypervisor or isolation provider. We may also create commercial products hypervisor or isolation provider. We may also create commercial products
intended for specific circumstances. There is one distinguished distribution intended for specific circumstances. There is one distinguished distribution
called **Qubes OS**. All source code for it is available for download under GPL called **Qubes OS**. All source code for it is available for download under a
license and is openly developed on the mailing lists. The rest of this document [free and open-source license](/doc/license/) and is openly developed on
discusses Qubes OS. Another remix may have its own version series. [GitHub](https://github.com/QubesOS) and our [mailing
lists](https://www.qubes-os.org/support/). The rest of this document discusses
Qubes OS. Another remix may have its own version series.
Release version ## Release versioning
---------------
Qubes OS as a whole is released from time to time. Version scheme for all Qubes OS as a whole is released from time to time. When preparing a new
releases is modeled after Linux kernel version numbers. When announcing a new release, we decide on the `<major>.<minor>` numbers (e.g., `3.0`). We then
release, we decide on the major.minor version (like `3.0`) and release publish the first release candidate, `3.0-rc1`. When we feel that enough
`3.0-rc1`. When we feel that enough progress has been made, we put `3.0-rc2` progress has been made, we'll release `3.0-rc2` and so on. All these versions
and so on. All these versions are considered unstable and not ready for (not yet releases) are considered unstable and not for production use. You are
production. You may ask for support on mailing lists (specifically welcome to [help us test](/doc/testing/) these versions.
**qubes-devel**), but it is not guaranteed (you may for example get answer
“update to newer `-rc`”). Public ISO image may or may not be available.
When enough development has been made, we announce the first stable version, When enough progress has been made, we announce the first stable release, e.g.
like e.g. `3.0.0` (i.e. without `-rc`). This version is considered stable and `3.0.0`. This not only a version but an actual release. It is considered stable
we support it for some period. Core components are branched at this moment and and we commit to supporting it according to our [support
bugfixes are backported from master branch. Please see [Help, Support, Mailing schedule](/doc/supported-releases/). Core components are branched at this
Lists, and Forum](/support/) for places to ask questions about stable releases. No major moment and bug fixes are backported from the master branch. Please see [help,
features and interface incompatibilities are to be included in this release. We support, mailing lists, and forum](/support/) for places to ask questions about
release bugfixes as `3.0.1`, `3.0.2` and so on, while new features come into the stable releases. No major features and interface incompatibilities are to be
next release e.g. `3.1-rcX`. included in this release. We release bug fixes as patch releases (`3.0.1`,
`3.0.2`, and so on), while backward-compatible enhancements and new features
are introduced in the next minor release (e.g., `3.1`). Any
backward-incompatible changes are introduced in the next major release (e.g.,
`4.0`).
Tickets in the tracker are sorted out by release major.minor, such as `3.0`, Issues in our [issue tracker](/doc/issue-tracking/) are sorted by release
`3.1` (trac calls this “milestone”). [milestones](/doc/issue-tracking/#milestones).
Release schedule ## Release schedule
----------------
There is no specific schedule for major and minor other that more general There is no specific schedule for releases other that more general
roadmap. When time comes, Supreme Committee declares feature freeze and tags roadmap. When time comes, Supreme Committee declares feature freeze and tags
`-rc1` and releases ISO image. From this time on, no new features are accepted. `-rc1` and releases ISO image. From this time on, no new features are accepted.
Also a strict time schedule kicks in. Also a strict time schedule kicks in.
Each release candidate period is as follows. For the first two weeks we accept Each release candidate period is as follows. For the first two weeks we accept
and assign bugreports to be fixed before next release candidate. For the next and assign bug reports to be fixed before next release candidate. For the next
two weeks we generally focus on fixing assigned bugreports, so issues discovered two weeks we generally focus on fixing assigned bug reports, so issues discovered
during this time may be postponed until later RC. Finally after that there is during this time may be postponed until later RC. Finally after that there is
one week of current-testing freeze, during which time no new packages are one week of current-testing freeze, during which time no new packages are
released, in hope that they will be installed by wider user base and tested. released, in hope that they will be installed by wider user base and tested.
@ -76,16 +88,11 @@ The next RC is released five weeks after the former. All packets are published
in `current` repository and the cycle starts over. There should be no less than in `current` repository and the cycle starts over. There should be no less than
1 and no more than 3 release candidates before final release. 1 and no more than 3 release candidates before final release.
<table> | stage | time |
<thead> | ------------------------ | --------- |
<tr><th>stage</th><th>time</th></tr> | initial testing | two weeks |
</thead> | bug fixing | two weeks |
<tbody> | `current-testing` freeze | one week |
<tr><td>initial testing</td><td>2 weeks</td></tr>
<tr><td>bug fixing</td><td>2 weeks</td></tr>
<tr><td>`current-testing` freeze</td><td>1 week</td></tr>
</tbody>
</table>
Starting with second cycle (that is, after `-rc1`) two weeks into the cycle Starting with second cycle (that is, after `-rc1`) two weeks into the cycle
(after primary bug-reporting period) the Supreme Committee decides whether there (after primary bug-reporting period) the Supreme Committee decides whether there
@ -95,36 +102,38 @@ no later than a week after.
!["Release cycle"](/attachment/doc/release-cycle.svg) !["Release cycle"](/attachment/doc/release-cycle.svg)
Bug priorities ## Bug priorities
--------------
When deciding whether the current release candidate is the final one, the Committee When deciding whether the current release candidate is the final one, the
takes bugs priorities into consideration. The meaning of them is as follows: Committee takes bug [priorities](/doc/issue-tracking/#priority) into
consideration. The meaning of them is as follows:
* `blocker` - when any such bug is present in the current release candidate, it - `blocker` --- when any such bug is present in the current release candidate,
can't be considered final release. Bugs with this priority must be fixed before it can't be considered final release. Bugs with this priority must be fixed
the next release candidate, even if that means delaying its release (which before the next release candidate, even if that means delaying its release
should be considered only last resort option). (which should be considered only last resort option).
* `critical` - when any such bug is present in the current release candidate, it - `critical` --- when any such bug is present in the current release candidate,
can't be considered final release. But such bugs are not qualified to delay it can't be considered final release. But such bugs are not qualified to
next release candidate release. delay next release candidate release.
* `major` - existence of such bugs do not strictly prevent the current release - `major` --- existence of such bugs do not strictly prevent the current
candidate be considered final (but of course we should try hard to not have release candidate be considered final (but of course we should try hard to
them there). Fixing bugs of this priority can be delayed and qualified as not have them there). Fixing bugs of this priority can be delayed and
updates to the final stable release. qualified as updates to the final stable release.
* `minor` - existence of such bugs do not prevent the current release candidate - `default` and `minor` --- existence of such bugs do not prevent the current
be considered final. Fixing such bugs can be delayed to the next Qubes OS release candidate be considered final. Fixing such bugs can be delayed to the
release. Eventually such fixes might be backported as an update to the stable next Qubes OS release. Eventually such fixes might be backported as an update
release(s). to the stable release(s). (`default` should really be assigned a more
specific priority, but in practice there are too many issues and not enough
time, so `default` ends up staying on many issues.)
All above is about bugs, no features should be assigned to the current release All above is about bugs, no features should be assigned to the current release
after first `-rc`. Supreme Committee is free to adjust priorities appropriately. after first `-rc`. Supreme Committee is free to adjust priorities
appropriately.
Component version ## Component version
-----------------
Qubes release is defined as specific versions of components, which are Qubes release is defined as specific versions of components, which are
developed more or less separately. Their versions are composed of major and developed more or less separately. Their versions are composed of major and
@ -143,24 +152,24 @@ for newer release some component should be downgraded. There is no guarantee
that arbitrary combination of different versions of random components will that arbitrary combination of different versions of random components will
yield usable (or even install-able) compilation. yield usable (or even install-able) compilation.
Git tags and branches ## Git tags and branches
---------------------
We mark each component version in the repository by tag containing We mark each component version in the repository by tag containing
`v<version>`. Likewise, each Qubes OS release is marked by `R<release>` tag. `v<version>`. Likewise, each Qubes OS release is marked by `R<release>` tag.
At the release of some release we create branches named like `release2`. Only At the release of some release we create branches named like `release2`. Only
bugfixes and compatible improvements are backported to these branches. These bug fixes and compatible improvements are backported to these branches. These
branches should compile. All new development is done in `master` branch. This branches should compile. All new development is done in `master` branch. This
branch is totally unsupported and may not even compile depending on maintainer branch is totally unsupported and may not even compile depending on maintainer
of repository. of repository.
All version and release tags should be made and signed by someone from ITL All version and release tags should be made and signed by someone from ITL
staff. Public keys are included in `qubes-builder` and available at staff. Public keys are included in `qubes-builder` and available at
[https://keys.qubes-os.org/keys/](https://keys.qubes-os.org/keys/). <https://keys.qubes-os.org/keys/>.
Check installed version ## Check installed version
-----------------
If you want to know which version you are running, for example to report If you want to know which version you are running, for example to report an
an issue, you can either check in the Qubes Manager menu under About / Qubes OS or in the file /etc/qubes-release in dom0. For the latter you can use a command like `cat /etc/qubes-release` in a dom0 terminal. issue, you can either check in the Qubes Manager menu under `About > Qubes OS`
or in the file `/etc/qubes-release` in dom0. For the latter you can use a
command like `cat /etc/qubes-release` in a dom0 terminal.