From 4f0c4711600ea3e9eab8eacd90b7b850c2518ef6 Mon Sep 17 00:00:00 2001
From: Martyn Welch <martyn.welch@collabora.com>
Date: Tue, 21 Jul 2020 11:48:50 +0100
Subject: [PATCH] Shift versioning and dch information out of
howtoreleasepackages
The versioning information doesn't sit very well in the releasing
packages guide. Add this to the information on binary package
versioning to make a more holistic page on versioning.
Move the information on dch tags to the version_control guide where
it is mentioned.
The rest of this guide is very out of date. We have a number of other
guides on releasing packages, drop this one.
Signed-off-by: Martyn Welch <martyn.welch@collabora.com>
---
content/architecture/api_stability.md | 6 +-
.../architecture/binary_package_versioning.md | 54 ----
content/architecture/versioning.md | 146 +++++++++
content/guidelines/howtoreleasepackages.md | 292 ------------------
content/guides/api_documentation.md | 2 +-
content/guides/version_control.md | 102 ++++--
6 files changed, 224 insertions(+), 378 deletions(-)
delete mode 100644 content/architecture/binary_package_versioning.md
create mode 100644 content/architecture/versioning.md
delete mode 100644 content/guidelines/howtoreleasepackages.md
diff --git a/content/architecture/api_stability.md b/content/architecture/api_stability.md
index 9c843cfdf..650637fcc 100644
--- a/content/architecture/api_stability.md
+++ b/content/architecture/api_stability.md
@@ -84,7 +84,7 @@ API stability guarantees are strongly linked to project versioning; both
package versioning and libtool versioning. Libtool versioning exists entirely
for the purpose of tracking ABI stability, and is explained in detail on the
[Autotools Mythbuster](https://autotools.io/libtool/version.html) or the
-[Versioning page]( {{< ref "/guidelines/howtoreleasepackages.md" >}} ).
+[Versioning page]( {{< ref "versioning.md#libtool-versioning" >}} ).
Package versioning (*major.minor.micro*) is strongly linked to API stability:
typically, the major version number is incremented when backwards-incompatible
@@ -92,8 +92,8 @@ changes are made (for example, when functions are renamed, parameters are
changed, or functions are removed). The minor version number is incremented
when forwards-incompatible changes are made (for example, when new public API
is added). The micro version number is incremented when code changes are made
-without modifying API. See the [Versioning page]( {{< ref
-"/guidelines/howtoreleasepackages.md" >}} ) for more information.
+without modifying API. See the
+[Versioning page]( {{< ref "versioning.md#package-versioning" >}} ) for more information.
API versioning is just as important for D-Bus APIs and GSettings schemas (if
they are likely to change) as for C APIs. See the [documentation on D-Bus API
diff --git a/content/architecture/binary_package_versioning.md b/content/architecture/binary_package_versioning.md
deleted file mode 100644
index 44e8e33dc..000000000
--- a/content/architecture/binary_package_versioning.md
+++ /dev/null
@@ -1,54 +0,0 @@
-+++
-date = "2019-11-15"
-weight = 100
-
-title = "Binary Package Versioning"
-
-aliases = [
- "/old-wiki/Build_and_Integration_infrastructure_documentation"
-]
-+++
-
-# Understanding Build Suffixes
-
-For every release (*Developer, Preview, Product*), we add a build suffix string
-to the packages, which relates to the release name of Apertis. The build
-suffix gets added to every built .deb package. Having a build suffix helps
-determine which Apertis release the .deb package was built for.
-
-The suffix string is constructed of: `b<Release_Name>b<B_CNT>`.
-- The initial `b` is for backward compatibility ensuring the new suffix string
- can work well together with older release packages.
-- `<Release_Name>` refers to the Apertis release's name.
-- `b<B_CNT>` refers to being a binary build along with the build count.
-
-For example, for the Apertis Developer Release `v2020dev0` we add the string
-`bv2020dev0b<B_CNT>` to the project configuration on OBS. Similarly, for an
-Apertis Product Release of `v2019.0` we add the string `bv2019.0b<B_CNT>` to
-the project configuration on OBS.
-
-## Point Releases
-
-A point release rolls the packages previously released in the update and
-security repositories into the stable branch. It is required to ensure that the
-packages in the new point release have a higher version than the binary package
-in the updates or security repositories, it is thus necessary to include the point
-releases numbering (e.g. `v2019.1`, `v2019.2`) in the build suffix.
-
-For example, during the initial release of the v2019 release, the build suffix
-was `bv2019.0b<B_CNT>`. The same build suffix is inherited by the updates and
-security sub-repositories during this time period. Before doing a new point
-release *v2019.1*, the build suffix of the main repositories
-(`apertis:v2019:target`, `apertis:v2019:development`, `apertis:v2019:sdk`,
-`apertis:v2019:hmi` etc) is set to `vb2019.1b<B_CNT>`.
-
-Once this step has been taken, changes previously commited to Apertis update
-and security branches (such as `apertis/v2020-updates` and
-`apertis/v2020-security`) are merged into the main release branch
-(`apertis/v2020`), thus triggering a build and generation of a package with the
-required point release suffix. This ensures that the packages synced from the
-updates and security sub-repositories have higher versions than packages from
-the updates and security sub-repositories. Once the merge has been completed,
-the equivalent packages in the update and security branches are purged to allow
-these branches to be used for following updates and security fixes to the new
-point release.
diff --git a/content/architecture/versioning.md b/content/architecture/versioning.md
new file mode 100644
index 000000000..c951191cf
--- /dev/null
+++ b/content/architecture/versioning.md
@@ -0,0 +1,146 @@
++++
+date = "2019-11-15"
+weight = 100
+
+title = "Versioning"
+
+aliases = [
+ "/architecture/binary_package_versioning/",
+ "/guidelines/versioning/",
+ "/old-wiki/Guidelines/Versioning",
+ "/old-wiki/Build_and_Integration_infrastructure_documentation"
+]
++++
+
+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
+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.
+
+## Libtool versioning
+
+Libraries have two version numbers: a libtool version which tracks ABI
+backwards compatibility, and a [package version](#package-versioning) which
+tracks feature changes. These are normally incremented in synchronisation, but
+should be kept separate because ABI backwards compatibility is not necessarily
+related to feature changes or bug fixes. Furthermore, the two version numbers
+have different semantics, and cannot be automatically generated from each
+other.
+
+A good overview of libtool versioning, and the differences from package
+versioning, is given in the
+[Autotools Mythbuster](https://autotools.io/libtool/version.html).
+
+To update the libtool version, follow the algorithm given in the comments
+below. This is a typical `configure.ac` snippet for setting up libtool
+versioning:
+
+```
+# Before making a release, the LT_VERSION string should be modified. The
+# string is of the form c:r:a. Follow these instructions sequentially:
+# 1. If the library source code has changed at all since the last update, then
+# increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
+# 2. If any interfaces have been added, removed, or changed since the last
+# update, increment current, and set revision to 0.
+# 3. If any interfaces have been added since the last public release, then
+# increment age.
+# 4. If any interfaces have been removed or changed since the last public
+# release, then set age to 0.
+AC_SUBST([LT_VERSION],[0:0:0])
+```
+
+The following snippet can be used in a `Makefile.am` to pass that version info
+to libtool:
+
+```
+my_library_la_LDFLAGS = -version-info $(LT_VERSION)
+```
+
+If a package contains more than one library, it should usually have a separate
+libtool version for each one.
+
+The standard process for making a release of a module increments the libtool
+version (if the module is a library) and the package version immediately before
+release. This is called pre-release incrementing.
+
+The use of pre-release increment for libtool versions means that they are only
+incremented once for all ABI changes in a release. Some projects use
+post-release increment for package versions to ensure that the package version
+number is not outdated (i.e. still equal to the previous release) during the
+development cycle; we achieve this by altering the version number automatically
+in
+[the build-snapshot script](https://gitlab.apertis.org/pkg/target/apertis-customizations/blob/apertis/v2020dev0/development/build-snapshot)
+instead.
+
+## 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
+Debian package for a library will use the library’s package version.
+
+Versions of packages developed for Apertis have the form `x.y.z` and are
+updated according to the following rules:
+
+- `x` starts at 0, and increments when there is a major compatibility break.
+ Libraries with different major versions should usually be
+ [parallel-installable]( {{< ref "module_setup.md#parallel-installability" >}} ).
+- `y` is the Apertis branch year and month as a single 4-digit number, for
+ instance `1706`.
+- `z` is 0 for the first release to each branch, and goes up for each release
+ (whether it is a feature release or bugfix-only).
+
+# Understanding Binary Build Suffixes
+
+For every binary release (*Developer, Preview, Product*), we add a build suffix
+string to the packages, which relates to the release name of Apertis. The
+build suffix gets added to every built .deb package. Having a build suffix
+helps determine which Apertis release the .deb package was built for.
+
+The suffix string is constructed of: `b<Release_Name>b<B_CNT>`.
+- The initial `b` is for backward compatibility ensuring the new suffix string
+ can work well together with older release packages.
+- `<Release_Name>` refers to the Apertis release's name.
+- `b<B_CNT>` refers to being a binary build along with the build count.
+
+The build count is incremented each time the package is built, regardless of
+whether the source has changed.
+
+For example, for the Apertis Developer Release `v2020dev0` we add the string
+`bv2020dev0b1` to the project configuration on OBS when the package is first
+built. Similarly, for an Apertis Product Release of `v2019.0` we add the
+string `bv2019.0b2` to the project configuration on OBS when it is built for
+the second time with no source change.
+
+# Product Point Release Versioning
+
+A product point release rolls the packages previously released in the update and
+security repositories into the stable branch. It is required to ensure that the
+packages in the new point release have a higher version than the binary package
+in the updates or security repositories, it is thus necessary to include the point
+releases numbering (e.g. `v2020.1`, `v2020.2`) in the build suffix.
+
+For example, during the initial release of the v2020 release, the build suffix
+was `bv2020.0b<B_CNT>`. The same build suffix is inherited by the updates and
+security sub-repositories during this time period. Before doing a new point
+release *v2020.1*, the build suffix of the main repositories
+(`apertis:v2020:target`, `apertis:v2020:development`, `apertis:v2020:sdk`,
+`apertis:v2020:hmi` etc) is set to `vb2020.1b<B_CNT>`.
+
+Once this step has been taken, changes previously commited to Apertis update
+and security branches (such as `apertis/v2020-updates` and
+`apertis/v2020-security`) are merged into the main release branch
+(`apertis/v2020`), thus triggering a build and generation of a package with the
+required point release suffix. This ensures that the packages synced from the
+updates and security sub-repositories have higher versions than packages from
+the updates and security sub-repositories. Once the merge has been completed,
+the equivalent packages in the update and security branches are purged to allow
+these branches to be used for following updates and security fixes to the new
+point release.
diff --git a/content/guidelines/howtoreleasepackages.md b/content/guidelines/howtoreleasepackages.md
deleted file mode 100644
index b639d751f..000000000
--- a/content/guidelines/howtoreleasepackages.md
+++ /dev/null
@@ -1,292 +0,0 @@
-+++
-date = "2019-10-24"
-weight = 100
-
-title = "How to Release Packages"
-
-aliases = [
- "/guidelines/versioning.md",
- "/old-wiki/Guidelines/Versioning",
- "/user_joykim/howtoreleasepackages.md",
- "/old-wiki/User:Joykim/HowToReleasePackages",
- "/old-wiki/Guidelines/HowToReleasePackages"
-]
-+++
-
-This document aims to explain how to release packages to Apertis
-projects.
-
-# Development workflow
-
-Apertis currently deals with two types of packages
-
- - Packages imported from upstream distributions: they live under
- [gitlab.apertis.org/pkg/](https://gitlab.apertis.org/pkg/) and
- follow the
- [Guidelines/Gitlab-based_packaging_workflow]( {{< ref "gitlab-based_packaging_workflow.md" >}} )
- - Packages for which Apertis is the upstream: they live under
- [appfw](https://gitlab.apertis.org/appfw),
- [hmi](https://gitlab.apertis.org/hmi), etc.
-
-# Writing commit messages suitable for generating `debian/changelog` with `gbp-dch`
-
-Commit messages should follow the [recommended
-style]( {{< ref "/guidelines/contribution_process.md#commit-message" >}} ).
-
-In addition,
-[gbp-dch](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/man.gbp.dch.html)
-is a tool to take those commit messages and automatically turn them in
-entries for `debian/changelog`.
-
-With it you can use the following tags in your commit messages:
-
- - `Gbp-Dch: {Full,Short}`
- - `Short` will create a short changelog entry using the short
- commit message (ie. the first line of the commit message)
- - `Full` will include the long description in the generated
- changelog entry
- - `Apertis: {$TASK_URL,$TASK_ID}`, is translated to `(Apertis: Txxxx)`
- in `debian/changelog` for automated task status tracking
- - `Thanks: $SOMEONE` if you want to give kudos to someone
-
-Running `gbp dch` will turn a commit message like:
-
-<code>
-
- Update website link to demo images
-
- The website has new path for demo images.
-
- Gbp-Dch: Full
- Apertis: https://phabricator.apertis.org/T12345
- Thanks: Mariano for pointing out the issue
-
- Signed-off-by: Héctor Orón MartÃnez <hector.oron@collabora.co.uk>
-
-</code>
-
-to the following `debian/changelog` entry:
-
-<code>
-
-```
- * Update website link to demo images.
- The website has new path for demo images.
- Signed-off-by: Héctor Orón MartÃnez <hector.oron@collabora.co.uk>
- Thanks to Mariano for pointing out the issue (Apertis: T12345)
-```
-
-</code>
-
-Just make sure your package has the following entries in
-`debian/gbp.conf`:
-
-<code>
-
- [dch]
- ignore-branch = True
- meta-closes = Apertis
- meta-closes-bugnum = (?:https://phabricator.apertis.org/)?(\T?\d+)
-
-</code>
-
-# Getting prepared for release
-
-## Preparing a GPG key
-
-While releasing, the maintainer should provide a GPG-signed version tag.
-If you have a GPG key already, please skip this section. Otherwise, you
-need to generate a new key by the following steps.
-
- $ gpg --gen-key
-
-At the prompt, you need to specify several options by interactive mode.
-In most cases, it provides the default values, but you can use the
-desired values for each question. After generating a key pair, you can
-use the command to list GPG keys.
-
- $ gpg --list-secret-keys --keyid-format LONG
- /Users/justin/.gnupg/secring.gpg
- --------------------------------
- sec 2048R/85AC7EE513BFB53B 2017-03-03
- uid Justin Kim <justin.kim@collabora.com>
- ssb 2048R/ADA53627F4F0C55C 2017-03-03
-
-From the list, the GPG key ID is *85AC7EE513BFB53B*. Now you need to let
-*git* know the key ID.
-
- $ git config --global user.signingkey "85AC7EE513BFB53B"
-
-## 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.
-
-### Libtool versioning
-
-Libraries have two version numbers: a libtool version which tracks ABI
-backwards compatibility, and a [package
-version](#package-versioning) which tracks feature changes.
-These are normally incremented in synchronisation, but should be kept
-separate because ABI backwards compatibility is not necessarily related
-to feature changes or bug fixes. Furthermore, the two version numbers
-have different semantics, and cannot be automatically generated from
-each other.
-
-A good overview of libtool versioning, and the differences from package
-versioning, is given in the [Autotools
-Mythbuster](https://autotools.io/libtool/version.html).
-
-To update the libtool version, follow the algorithm given in the
-comments below. This is a typical `configure.ac` snippet for setting up
-libtool versioning:
-
- # Before making a release, the LT_VERSION string should be modified. The
- # string is of the form c:r:a. Follow these instructions sequentially:
- # 1. If the library source code has changed at all since the last update, then
- # increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
- # 2. If any interfaces have been added, removed, or changed since the last
- # update, increment current, and set revision to 0.
- # 3. If any interfaces have been added since the last public release, then
- # increment age.
- # 4. If any interfaces have been removed or changed since the last public
- # release, then set age to 0.
- AC_SUBST([LT_VERSION],[0:0:0])
-
-The following snippet can be used in a `Makefile.am` to pass that
-version info to libtool:
-
- my_library_la_LDFLAGS = -version-info $(LT_VERSION)
-
-If a package contains more than one library, it should usually have a
-separate libtool version for each one.
-
-The standard process for making a release of a module increments the
-libtool version (if the module is a library) and the package version
-immediately before release. This is called pre-release incrementing.
-
-The use of pre-release increment for libtool versions means that they
-are only incremented once for all ABI changes in a release. Some
-projects use post-release increment for package versions to ensure that
-the package version number is not outdated (i.e. still equal to the
-previous release) during the development cycle; we achieve this by
-altering the version number automatically in [the build-snapshot
-script](https://gitlab.apertis.org/infrastructure/apertis-customizations/blob/apertis/v2020dev0/development/build-snapshot)
-instead.
-
-### 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 Debian package for a library will use the library’s
-package version.
-
-Versions of packages developed for Apertis have the form `x.y.z` and are
-updated according to the following rules:
-
- - `x` starts at 0, and increments when there is a major compatibility
- break. Libraries with different major versions should usually be
- [parallel-installable]( {{< ref "module_setup.md#parallel-installability" >}} ).
- - `y` is the Apertis branch year and month as a single 4-digit number,
- for instance `1706`.
- - `z` is 0 for the first release to each branch, and goes up for each
- release (whether it is a feature release or bugfix-only).
-
-# Release process
-
-The packages maintained in the [Apertis git
-repositories](https://git.apertis.org) should be released with the
-following procedure, roughly based on the [GNOME release
-process](https://wiki.gnome.org/MaintainersCorner/Releasing). The
-commands below assume you're running the
-[Apertis SDK](https://designs.apertis.org/latest/software-development-kit.html).
-
-1. Make sure all the `git-buildpackage` local branches (`apertis/*`,
- `upstream/*` and `pristine-tar`) are available and up-to-date:
- <code>
- $ gbp pull
- </code>
-2. Choose the new version number by the rules of [Libtool
- versioning](#libtool-versioning) and [Package
- versioning](#package-versioning)
-3. Make sure you have no local changes and you are in right branch
- <code>
- $ git status
- </code>
-4. `configure.ac`: bump for a new upstream release, unless the module
- uses `git-version-gen` in which case you don't need to do anything.
-5. `debian/changelog`: [auto-generate the changelog
- entry](#generate-debian.2fchangelog-from-the-git-log-with-gbp-dch)
- and mark it for release replacing `UNRELEASED` with the current
- version (for instance `16.12`) <code>
- $ gbp dch --auto -R
- </code>
-6. Make sure that all tasks this release is fixing [are
- mentioned](https://designs.apertis.org/latest/contribution-process.html#automatically-closing-tasks)
- in `debian/changelog` in the form `(Apertis: T1234)`
-7. For a library: check that any `Since: UNRELEASED` annotations have
- been replaced with `Since: 0.1612.1` or whatever, for example using
- `git grep UNRELEASED`
-8. For a library: bump the Libtool current/revision/age versions in
- `configure.ac`
-9. Build test the package with
- [`build-snapshot`](https://gitlab.apertis.org/infrastructure/apertis-customizations/blob/apertis/v2020dev0/development/build-snapshot)
- <code>
- $ build-snapshot localhost
- </code>
-10. For a library: look for output from `dpkg-makeshlibs` reporting new
- symbols that should be in the `.symbols` files. Add them to the
- `.symbols` files, with the upstream version (for example
- `mylib_foo@Base 0.1612.0`, not `mylib_foo@Base 0.1612.0-0co1`).
-11. Now you need the following variables for the next steps. <code>
- PACKAGE=$(dpkg-parsechangelog -SSource)
- DEBVERSION=$(dpkg-parsechangelog -SVersion)
- VERSION=${DEBVERSION%%-*}
- RELEASE=$(dpkg-parsechangelog -SDistribution)
- COMPONENT=$(cat debian/source/apertis-component)
- </code> If `build-snapshot` succeeds, commit the changes. <code>
- $ git commit --all --signoff -m "Release $PACKAGE version $DEBVERSION"
- </code>
-12. Submit a merge request for review following the [contribution
- process
- guidelines](https://designs.apertis.org/latest/contribution-process.html),
- paying special attention to the section about [release
- commits](https://designs.apertis.org/latest/contribution-process.html#release-commits)
- if you are releasing a new version of the package.
-13. Skip this if you are only releasing changes under the `debian/`
- folder and not doing an upstream release at the same time:
- 1. If you're doing an upstream release, tag it (note the versioning
- must have a <strong>`v`</strong>, for instance `v1.2.3`). <code>
- $ git tag v$VERSION -s -m "Release $PACKAGE $VERSION"
- </code>
-14. Tag the Apertis release. <code>
- $ gbp buildpackage --git-tag --git-tag-only --git-ignore-branch
- </code>
-15. Run `build-snapshot` again. This is because the build procedure is
- slightly different with the tags.
-16. Push the tags and push the changes (in that order so CI never builds
- these commits without the tags being present) <code>
- $ git push origin v$VERSION apertis/$VERSION
- $ git push
- </code>
-17. If you happened to push the commits *before* the tags, you will need
- to manually trigger the corresponding CI job on Jenkins (or ask
- someone to do it for you)
-18. Wait for an OBS maintainer to accept the request to merge the
- package built in the corresponding `apertis:$RELEASE:snapshots`
- project.
-
-# Work done
-
-Once accepted by OBS maintainer, you can update the package by `apt-get`
-after a daily Apertis image is released.
-
-# External links
-
- - [Autotools Mythbuster guide to library
- versioning](https://autotools.io/libtool/version.html)
- - [libtool manual page on version
- info](http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html)
- - [GNOME release process
- instructions](https://wiki.gnome.org/MaintainersCorner/Releasing)
diff --git a/content/guides/api_documentation.md b/content/guides/api_documentation.md
index 48c61bcf4..908c63256 100644
--- a/content/guides/api_documentation.md
+++ b/content/guides/api_documentation.md
@@ -228,7 +228,7 @@ Whenever a symbol is added to the public API, it should have a documentation
comment added. This comment should always contain a `Since` line with the
package version number of the release which will first contain the new API.
This should be the number currently in `configure.ac` if
-[post-release version incrementing]( {{< ref "howtoreleasepackages.md#release-process" >}} )
+[post-release version incrementing]( {{< ref "versioning.md#libtool-versioning" >}} )
is being used.
e.g.
diff --git a/content/guides/version_control.md b/content/guides/version_control.md
index 83b3e2e9c..2684fac59 100644
--- a/content/guides/version_control.md
+++ b/content/guides/version_control.md
@@ -123,42 +123,88 @@ style and formatting to be used:
- the longer
[Linux kernel style guide for commit messages](https://www.kernel.org/doc/html/v4.14/process/submitting-patches.html#describe-your-changes)
-A few rules are automatically checked by the Apertis infrastructure:
+Minimally the following should be followed:
- Subject: less than 50 characters
- Body: each line should be less than 72 characters long
- A `Signed-off-by` tag must be present as a
[Developer Certificate of Origin](https://developercertificate.org/)
-Tags can be used to
-[make commit messages suitable for automatically generating `debian/changelog`]( {{< ref "/guidelines/howtoreleasepackages.md#writing-commit-messages-suitable-for-generating-debian/changelog-with-gbp-dch" >}} ).
-
Here's
[an example](https://git.apertis.org/cgit/canterbury.git/commit/?id=6338e04aeefe):
-
- CbyServiceManager: Instruct systemd to send SIGKILL after 10s
-
- After executing the ExecStop command-line or sending SIGTERM,
- by default systemd will wait up to 90 seconds for a service to exit
- before it becomes impatient and sends SIGKILL. This seems far too long
- for our use-case; wait 10 seconds instead.
-
- The choice of this arbitrary timeout is a trade-off. If it is too
- short, applications with a lot of state to serialize to disk might
- be killed before they have done so (we'd better hope they're using
- crash-safe I/O patterns like g_file_set_contents()). If it is too
- long, a user uninstalling an app-bundle will be left waiting
- a long time.
-
- When Ribchester calls TerminateBundle (T2696) it will need to wait
- a little longer than this; whatever timeout it uses, a broken or
- compromised per-user instance of Canterbury would be able to delay
- app-bundle upgrade, rollback or removal by up to that long.
-
- Apertis: https://phabricator.apertis.org/T12345
- Signed-off-by: Simon McVittie <smcv@collabora.com>
- Reviewed-by: Frédéric Dalleau <frederic.dalleau@collabora.co.uk>
- Differential Revision: https://phabricator.apertis.org/D7088
+```
+CbyServiceManager: Instruct systemd to send SIGKILL after 10s
+
+After executing the ExecStop command-line or sending SIGTERM,
+by default systemd will wait up to 90 seconds for a service to exit
+before it becomes impatient and sends SIGKILL. This seems far too long
+for our use-case; wait 10 seconds instead.
+
+The choice of this arbitrary timeout is a trade-off. If it is too
+short, applications with a lot of state to serialize to disk might
+be killed before they have done so (we'd better hope they're using
+crash-safe I/O patterns like g_file_set_contents()). If it is too
+long, a user uninstalling an app-bundle will be left waiting
+a long time.
+
+When Ribchester calls TerminateBundle (T2696) it will need to wait
+a little longer than this; whatever timeout it uses, a broken or
+compromised per-user instance of Canterbury would be able to delay
+app-bundle upgrade, rollback or removal by up to that long.
+
+Apertis: https://phabricator.apertis.org/T12345
+Signed-off-by: Simon McVittie <smcv@collabora.com>
+Reviewed-by: Frédéric Dalleau <frederic.dalleau@collabora.co.uk>
+Differential Revision: https://phabricator.apertis.org/D7088
+```
+
+Tags can be used in commit messages to enhance the information recorded in the
+`debian/changelog` by
+[gbp-dch](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/man.gbp.dch.html).
+`gbp-dch` is a tool that parses the commit messages and automatically turns
+them in entries for `debian/changelog`.
+
+With it you can use the following tags in your commit messages:
+
+- `Gbp-Dch: {Full,Short}`
+ - `Short` will create a short changelog entry using the short commit message
+ (ie. the first line of the commit message). This is the default.
+ - `Full` will include the long description in the generated changelog entry
+- `Thanks: $SOMEONE` if you want to give kudos to someone
+- `Apertis: {$TASK_URL,$TASK_ID}`, is translated to `(Apertis: Txxxx)` in
+ `debian/changelog` for automated task status tracking
+
+For the last tag to work, the package requires the following entries in
+`debian/gbp.conf`:
+
+```
+[dch]
+meta-closes = Apertis
+meta-closes-bugnum = (?:https://phabricator.apertis.org/)?(\T?\d+)
+```
+
+Running `gbp dch` will turn a commit message like:
+
+```
+Update website link to demo images
+
+The website has new path for demo images.
+
+Gbp-Dch: Full
+Apertis: https://phabricator.apertis.org/T12345
+Thanks: Mariano for pointing out the issue
+
+Signed-off-by: Héctor Orón MartÃnez <hector.oron@collabora.co.uk>
+```
+
+to the following `debian/changelog` entry:
+
+```
+ * Update website link to demo images.
+ The website has new path for demo images.
+ Signed-off-by: Héctor Orón MartÃnez <hector.oron@collabora.co.uk>
+ Thanks to Mariano for pointing out the issue (Apertis: T12345)
+```
# Merging procedure
--
GitLab