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: Martyn Welch <martyn.welch@collabora.com>

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