Update Git-related documents according to the current practice

Signed-off-by: Andrej Shadura <andrew.shadura@collabora.co.uk>

content/guides/apertis_packaging_guide.md

@@ -189,7 +189,7 @@ would lead to errors difficult to diagnose.
 When targeting a specific release, `~${RELEASE}.${COUNTER}` needs to be
 appended to the version identifier after the local build suffix:
 
-* `0.42` → append `co1~v2020pre.0` → `0.42co1~v2020pre.0`
+* `0.42` → append `co0~v2020pre.0` → `0.42co0~v2020pre.0`
 * `0.42co3` → bump to `co4` and append `~v2020pre.0`→ `0.42co4~v2020pre.0`
 * `0.42co4~v2020pre.0` → increase the release-specific counter → `0.42co4~v2020pre.1`
 
@@ -211,22 +211,19 @@ This is the process to import a new package from Debian to Apertis:
 * invoke `import-debian-package` from the [packaging-tools
   repository](https://gitlab.apertis.org/infrastructure/packaging-tools/)
   to populate the local git repository:
-  * fetch a specific version: `import-debian-package --upstream buster --downstream apertis/v2020dev0 --create-ci-branches --package hello --version 2.10-2`
-  * fetch the latest version: `import-debian-package --upstream buster --downstream apertis/v2020dev0 --create-ci-branches --package hello`
+  * fetch a specific version: `import-debian-package --upstream buster --downstream apertis/v2020dev0 --component target --create-ci-branches --package hello --version 2.10-2`
+  * fetch the latest version: `import-debian-package --upstream buster --downstream apertis/v2020dev0 --component target --create-ci-branches --package hello`
+  * the argument to `--component` reflects the repository component it is part of (for instance, `target`); it will be stored in `debian/apertis/component`
   * multiple downstream branches can be specified, in which case all of them
     will be updated to point to the newly imported package version
+  * the Apertis version of the package will have a local suffix (`co0`) appended
   * don't use `import-debian-package` on existing repositories, it does not
     attempt to merge `apertis/*` branches and instead it re-sets them to new
     branches based on the freshly imported Debian package
-* Add a `debian/apertis/component` file reflecting the repository component it is part of (for instance, `target`)
-  * check out the apertis repository: `git checkout apertis/v2021dev0`
-  * add the component file: `echo target > debian/apertis/component`
-  * add the component file to git: `git add debian/apertis/component`
-  * commit the file: `git commit -m "Add debian/apertis/component file pointing to target" debian/apertis/component`
-* create an empty project on GitLab under the `pkg/*` namespaces (for instance, `pkg/target/hello`)
-* configure the origin remote on your local git: `git remote add origin git@gitlab.apertis.org:pkg/target/hello`
+* create an empty project on GitLab under the `pkg/*` namespaces (for instance, `pkg/hello`)
+* configure the origin remote on your local git: `git remote add origin git@gitlab.apertis.org:pkg/hello`
 * push your local git contents to the newly created GitLab project: `git push --all --follow-tags origin`
-* set it up with `gitlab-rulez apply rulez.yaml --filter pkg/target/hello` from
+* set it up with `gitlab-rulez apply rulez.yaml --filter pkg/hello` from
   the [gitlab-rulez repository](https://gitlab.apertis.org/infrastructure/gitlab-rulez)
   * sets the CI config path to `debian/apertis/gitlab-ci.yml`
   * changes the merge request settings:
@@ -365,8 +362,8 @@ is not released into any of the Debian releases. In such case, we can try:
 * Generate a source package out of the packaging repository using `gbp buildpackage -S`
   * If successful, this will give us a proper *libgpiod source package*.
 * Clone the Apertis libgpiod git packaging repostiory
-  * Use the [import-tarballs](https://gitlab.apertis.org/infrastructure/packaging-tools/-/blob/master/import-tarballs) tool to import the source package generated from the Debian repository into Apertis packaging repository. Eg. `import-tarballs libgpiod-1.4.2-1.dsc`
-  * Note: The `import-tarballs` script imports the new tarball into the git repository and commits it to the `pristine-lfs` branch. While, a user can commit to the branch manually by-hand, we recommend the use of the `import-tarballs` tool to import new tarballs and commiting them to the packaging repository
+  * Use the `pristine-lfs` tool to import the source package generated from the Debian repository into Apertis packaging repository. Eg. `pristine-lfs import-dsc libgpiod-1.4.2-1.dsc`
+  * Note: The `import-dsc` subcommand imports the new tarball into the git repository and commits it to the `pristine-lfs` branch. While a user can commit to the branch manually by-hand, we recommend the use of `import-dsc` to import new tarballs and committing them to the packaging repository
 
 ## License scans
 
@@ -431,6 +428,8 @@ Main components:
   upstream original tarballs and packaging source tarballs using Git-LFS, as a
   more robust replacement for `pristine-tar`
 
+![DEP-14 in Apertis](/images/apertis-dep-14-gitlab-curves.svg)
+
 Branches:
 * `pristine-lfs`: stores references to the Git-LFS-hosted original tarballs
 * `debian/$DEBIAN_RELEASE` (for instance, `debian/buster`): contains the extracted
@@ -438,7 +437,7 @@ Branches:
 * `pristine-lfs-source`: stores references to the Git-LFS-hosted packaging
   tarballs, mainly to ensure that each (package, version) tuple is built only
   once and no conflicts can arise
-* `apertis/$APERTIS_RELEASE` (for intance, `apertis/v2020dev0`): contains the
+* `apertis/$APERTIS_RELEASE` (for instance, `apertis/v2020dev0`): contains the
   extracted upstream sources and possibly patched packaging information for
   Apertis, including the `debian/apertis/gitlab-ci.yaml` to set up the
   GitLab-to-OBS pipeline

content/guides/version_control.md

@@ -71,6 +71,13 @@ project such as `dbus`, the git repositories follow these rules:
   based, should be imported onto `debian/${UPSTREAM_DISTRIBUTION}` (e.g.
   `debian/buster`). The required process is covered in the
   [ci-package-builder documentation](https://gitlab.apertis.org/infrastructure/ci-package-builder#adding-new-packages-from-debian).
+- Each version of an Apertis package derived from a Debian package must
+  have a local version suffix. If the Apertis package has no functional
+  changes and the only difference from the upstream is metadata under
+  `debian/apertis/`, the suffix should be `co0`. Due to how Debian packaging
+  tools work, this version change must be reflected in by adding a new entry
+  at the top of `debian/changelog` with the distribution field set to
+  `apertis`.
 
 # Guidelines for making commits