diff --git a/content/guides/apertis_packaging_guide.md b/content/guides/apertis_packaging_guide.md
index 97492f0339324cefc255ef122c9466c6a128a2e7..87a50ffe6b51abfe323623111b43683e927419f0 100644
--- a/content/guides/apertis_packaging_guide.md
+++ b/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`
+
+
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
diff --git a/content/guides/version_control.md b/content/guides/version_control.md
index 2684fac591cafebeb8bf5717a5f636a4a2cdc174..987b4a54d694d1c2b48f59086a557d460219e926 100644
--- a/content/guides/version_control.md
+++ b/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