Skip to content
Snippets Groups Projects
Commit d7a1468a authored by Martyn Welch's avatar Martyn Welch Committed by Emanuele Aina
Browse files

Add documentation regarding Debian revisions


We have very little documentation regarding the handling of Debian
revisions but we need to update these more frequently than raw version
numbers. Pull some documentation from a training session guide written
a while back to fill this hole.

Signed-off-by: default avatarMartyn Welch <martyn.welch@collabora.com>
parent 4f0c4711
No related branches found
No related tags found
1 merge request!45Reformat and move contents of guidelines
......@@ -16,14 +16,102 @@ It is important to properly
[version](https://en.wikipedia.org/wiki/Software_versioning) software to enable
software changes and compatibility of components to be tracked, as well as to
aid with bug tracking and the application of updates. To achieve this, it is
important that we effectively version each source module, binary package and
important that we effectively version each source component, binary package and
release.
# Module Versioning
Module versioning differs for libraries and applications: libraries need a
libtool version specified in addition to their package version. Applications
just have a package version.
The approach to versioning depends on the entity being versioned and in the
case of source code whether it is developed specifically for Apertis or an
existing project used by Apertis.
# Debian Versions and Revisions
The vast majority of the components from which the Apertis distribution is
derived are taken from Debian. A large percentage of the packages in Debian are
created from source code from other software projects. Each Debian package
retains the version set by its upstream (the project from which the source was
taken). Debian appends its own package revision to the end of the version. The
revision is very important when working with software distributions as this
enables tracking of changes across security updates, backports, binary
rebuilds, etc.
As an example, imagine an upstream project producing an application called
`hello` releases version `1.0`, A Debian packager takes it and makes it’s first
release in Debian, following the standards the packager gives the package the
version `1.0-1`, the first Debian package release. After a while the packager
adds some improvements to the packaging, allowing it to cross build, but with
the package still based on the upstream `1.0` release. The package is then
released as `1.0-2`. In the meanwhile, the package is frozen and goes into
production, as a so called stable release. Now, the packager continues
development and does several Debian updates, creating up to `1.0-7`. At this
point we’ve got `1.0-2` in a stable distribution and `1.0-7` in a development
distribution. The convention is documented the
[Debian policy](https://www.debian.org/doc/debian-policy/#version). If we find
a security issue in stable we want to fix it, but want to keep current version,
how would that be named so that version-revision will not conflict with other
changes? What about if we want to backport the version in development, to build
against stable branch? What about us, as a downstream of the Debian package,
how should we version the package if we want to apply some changes on top of
Debian package? The convention, when modifiying the package for security
updates, backports and downstream modification, is to append to the end of the
existing Debian version number. As a result of this policy, many packages in
Apertis bear the addition `coX`, where `X` is a incremented number, which
shows the number of modifications made to the package by Collabora for Apertis.
Additionally, there are a number of symbols that are used to separate these
portions of the revision. The symbol `~` is used to infer "less", and `+` for
"more". For example, `1.0-1+co1` is considered greater than `1.0-1`, but
`1.0-1~co1` is lower version than `1.0-1`. This ensures that we don’t end up
creating packages whose versioning collides with later upstream versioning and
allows us to control which package is preferred over another by the package
manager which ulitimately uses the version/revision string to decide which
package to install.
Further examples:
- `1.0-2deb9u1`:
- Debian security update `1` for the Debian `9` distribution
- Applied to the second revision of Debian’s packaging for the upstream `1.0`
release.
- `1.0-2+b1`:
- Binary rebuild of the second revision of Debian’s packaging for the
upstream `1.0` release.
- No changes to the source.
- `1.0-2co1`:
- Modification `1` by Collabora
- Applied to the second revision of Debian’s packaging for the upstream `1.0`
release.
- `1.0-2ubuntu3co4foo5`:
- Foo modification revision `5`
- Using the Apertis modification revision `4`
- Based on Ubuntu's modification revision `3`
- Which was based on the second revision of Debian’s packaging for the
upstream `1.0` release.
- `1.0-7~bpo9+1`:
- First revision of a backport to Debian `9`
- Which is based on revision `7` of Debian’s packaging for the upstream `1.0`
release.
- The `~` ensures that if the installation is upgraded to Debian 10, which
uses `1.0-7`, the backport is considered less than this and the "newer"
package (i.e. the one from Debian 10) gets installed.
If in doubt, we can check on the command line:
$ dpkg --compare-versions 1.0-1+co1 gt 1.0-1 && echo YES
$ dpkg --compare-versions 1.0-1~co1 lt 1.0-1 && echo YES
Here `gt` stands for “greater than”, while `lt` means “less than”.
When making modifications to existing packages, the above rules should be used
to determine a suitable version.
# Apertis Source Code Versioning
For packages written specifically for Apertis the package is maintained as a
[native package](https://www.debian.org/doc/manuals/maint-guide/advanced.en.html#native-dh-make).
When handling such packages we directly modify the version number rather than
appending a revision. Source Code versioning differs for libraries and
applications. Applications just require a package version, libraries need a
libtool version specified in addition to their package version.
## Libtool versioning
......@@ -80,7 +168,7 @@ in
[the build-snapshot script](https://gitlab.apertis.org/pkg/target/apertis-customizations/blob/apertis/v2020dev0/development/build-snapshot)
instead.
## Package versioning
## Package Versioning
The package version number for a library is that passed to `AC_INIT()`, and the
one which is typically known as the project’s version number. For example, the
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment