Commit 32acd3c2 authored by Martyn Welch's avatar Martyn Welch

Updates from document review

The review process for this document highlighted a missing bracket and a
number of sections that no longer make sense to have included in this
document which now focuses on upstream contributions.

Add the missing bracket and remove the unneeded sections from the
document. API review documentation moved to: default avatarMartyn Welch <>
parent 3b883be7
......@@ -259,7 +259,7 @@ git commit -i -s
the commit message.
* Add a `Fixes: APERTIS-<task_id>` tag for each task in the proposed commit
messages (as explained in the section "Automatically closing tasks" below or
in the envelope message of the merge request itself in order to link the
in the envelope message of the merge request itself) in order to link the
merge request to one or more tasks in Phabricator.
* Note: The tag will ensure that Phabricator tasks are kept up-to-date with
regard to the status of related merge requests, through the creation of a new
......@@ -321,10 +321,11 @@ git commit -i -s
### Extra Actions
* If other actions need to be manually taken when commits are landed (for
instance, updating the jobs on Jenkins when changing the templates) the
developer accepting and merging the changes is responsible for ensuring that
those actions are taken, either by doing them themselves or by asking someone
else to do that.
[triggering the `tag-release` pipeline](
the developer accepting and merging the changes is responsible for ensuring
that those actions are taken, either by doing them themselves or by asking
someone else to do that.
* If the merged commits need to be backported to other branches through
cherry-pick or merges, those should go through merge requests as well:
however, only changes related to the backport process are allowed, unrelated
......@@ -365,45 +366,6 @@ described in section 11 of the
[kernel guide to submitting patches](
## Automatically closing tasks
You should never close a task manually. To automatically close the task when
your changes appear in the packages, add a meta-tag in the git commit message
description, pointing to one or more Apertis tasks, each on its own line:
Fixes: APERTIS-<task_id>
When `debian/changelog` file is generated from the commit messages by
`gbp dch`, that meta-tag is transformed into `(Fixes: APERTIS-T12345)` appended
to the changelog message. When the package is built and uploaded, the task will
be automatically closed.
By default, only the first line of the commit message is used for the changelog
For example, for a commit message like this:
Update website link to demo images
The website has new path for demo images.
Fixes: APERTIS-T12345
Thanks: John Smith for pointing out the issue
Signed-off-by: Random J Developer <>
will be converted into the following changelog entry:
* Update website link to demo images.
Thanks to John Smith for pointing out the issue (Fixes: APERTIS-T12345)
## Privileged processes
Pushing commits to requires commit rights which are only
......@@ -436,58 +398,3 @@ Apertis infrastructure, please send an email to
- Your full name
- The email address you prefer to be contacted through
- The nickname/account name you wish to be known by on the Apertis GitLab
## API review process
Before a public API may be marked as stable and suitable for use by third-party
apps, it must be reviewed. The process for this is:
* Some or all of the APIs of a component are selected for review. For example,
it might be decided to review the C APIs for a component, but not the D-Bus
APIs which it uses internally to communicate with a background service.
* The component authors produce:
* A description of the goals of the component and the APIs under review.
These should be high-level descriptions, covering the use cases for that
component and its APIs, goals of the implementation, and specific
non-goals. Where possible, this should refer back to a design document.
These descriptions should *not* be simply a copy of the API documentation
describing *how* the goals are implemented.
* A list of required features and APIs which must pass review before the API
may be marked as stable.
* A list of other components which depend on the APIs under review, and a
description of how those other components should interact with the APIs
under review. This ensures the final APIs are still usable as intended from
other components, and is another way of describing the use cases of the
* An explicit description of where privilege boundaries are required in the
system, and whether any of the APIs cross those boundaries (for example, if
they implement functionality which should not be callable without elevated
* A description of how the API may need to be extended. For example, should
it be extensible by the component maintainers, by third-party apps, or not
at all?
* The reviewers examine the APIs and provided documentation, and make
recommendations for the component as a whole, its interactions with other
components, and specific recommendations for each API under review (for
example, ‘keep this API unchanged’, ‘remove this API’, ‘keep it with the
following changes’, etc.). See the
[API design guidelines]( for
some principles that the reviewers might apply.
* The feedback is discussed, potentially iterated, and changes are made to the
public API accordingly.
* The changes are re-reviewed, and the process iterates until the reviewers are
* The APIs are marked as public and stable, and their API documentation is
The main goal of the review process is to ensure that the stable APIs, which
have to be supported for a long time in the future, are a good match for all
current and anticipated use cases, and follow good system architecture
practices. A large part of this effort is in ensuring that all use cases for
the APIs are known and documented. A *non-goal* of the review process is to
look at each API individually and mechanically run through some ‘API review
checklist’ — this can easily miss mismatches between the API and the
component’s use cases; architectural issues which are important to catch.
Components’ APIs should not be marked as stable until they have been reviewed.
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment