versioning: Describe the use of the +apertisX suffix

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

content/architecture/versioning.md

@@ -24,6 +24,18 @@ 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.
 
+The overall rules for Apertis are:
+
+* Apertis-specific packages are handled as native Debian packages, with a
+  simple version without any suffixes, for instance `1.12.3` or `0.2022.3`
+* Non native packages get a `+apertisX` revision suffix appended, for instance
+  `5.55-3+apertis0` or `2.31-13+deb11u2+apertis1`
+* Downstream append their own suffix as well, for instance the downstream Foo
+  would have `5.55-3+apertis0+foo2` or `2.31-13+deb11u2+apertis1+foo0`
+* OBS appends a `b${RELEASE}b${BUILDCOUNT}` suffix like `bv2022.0b2` or
+  `bv2023dev1b1` only to binary packages to ensure each rebuild gets a unique
+  identifier, yielding versions like `2.31-13+deb11u2+apertis1b2022.0b1`
+
 # Debian Versions and Revisions
 
 The vast majority of the components from which the Apertis distribution is
@@ -55,17 +67,20 @@ how should we version the package if we want to apply some changes on top of
 Debian package?  The convention, when modifying 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, packages in
-Apertis bear the addition `apertisX`, where `X` is a incremented number, which
+Apertis bear the addition `+apertisX`, where `X` is a incremented number, which
 shows the number of modifications made to the package by the Apertis team.
-The `apertis0` suffix means that the only difference between the upstream package
+The `+apertis0` suffix means that the only difference between the upstream package
 from Debian and the package in Apertis is the metadata under `debian/apertis/`
 and the changelog entry itself. This is to highlight the fact that this metadata
 ends up in the generated source package, so this source package carries a
 small delta against the corresponding Debian package.
 
-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+apertis1` is considered greater than `1.0-1`, but
+The `+` has no special treatment in version comparison, but it has been chosen
+to avoid conflicts with the build suffix appended by OBS.
+
+The symbol `~` is instead special-cased to sort lower than anything else, which
+can be useful in some very particular cases. For example, `1.0-1+apertis1` is
+considered greater than `1.0-1`, but
 `1.0-1~apertis1` 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
@@ -82,12 +97,12 @@ Further examples:
   - Binary rebuild of the second revision of Debian’s packaging for the
     upstream `1.0` release.
   - No changes to the source.
-- `1.0-2apertis1`:
+- `1.0-2+apertis1`:
   - Modification `1` by the Apertis team
   - Applied to the second revision of Debian’s packaging for the upstream `1.0`
     release.
-- `1.0-2ubuntu3apertis4foo5`:
-  - Foo modification revision `5`
+- `1.0-2ubuntu3+apertis4+foo5`:
+  - Foo downstream 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
@@ -110,6 +125,28 @@ 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.
 
+# Why the `+apertisX` suffix has been chosen
+
+The `+apertisX` suffix was chosen over other options like `apertisX` because
+the latter may conflict with the build suffix appended by OBS.
+
+For instance:
+1. `bluez` in Debian has the `5.55-3` version
+2. it gets mistakenly uploaded to OBS with no changes, forgetting to add
+   any suffix
+3. OBS appends the build suffix, generating binaries with version `5.55-3bv2022.0b1`
+4. the `bluez` source gets patched in Apertis and a suffix is appended:
+   `apertisX` would yield `5.55-3apertis1` while `+apertisX` would yield `5.55-3+apertis1`
+5. OBS appends the build suffix, generating binaries with version, respectively,
+   `5.55-3apertis1bv2022.0b1` or `5.55-3+apertis1b2022.0b1`
+6. the APT published gets the new binaries from OBS: `5.55-3+apertis1b2022.0b1`
+   sorts newer than the already published `5.55-3bv2022.0b1` so it correctly
+   replaces it, while `5.55-3apertis1bv2022dev2b1` would sort lower than
+   `5.55-3bv2022.0b1` and it would get erroneously discarded.
+
+Older Apertis releases used the `coX` suffix only for packages with downstream
+changes, and started enforcing the `+apertisX` suffix from the v2022 cycle.
+
 # Apertis Source Code Versioning
 
 For packages written specifically for Apertis the package is maintained as a