diff --git a/content/architecture/versioning.md b/content/architecture/versioning.md index c951191cf6d426808eba6763a716e7aef61773c0..a1da6f4bde2286691c68233ec7c95886bc639784 100644 --- a/content/architecture/versioning.md +++ b/content/architecture/versioning.md @@ -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