Rework component guide

The workflows in component guide target Apertis maintainers more than developers, it is also out-of-date in some places. Update this guide and make it more relevant to non-maintainers in the process.

Signed-off-by: Martyn Welch martyn.welch@collabora.com

content/guides/buildingpatchingandmaintainingtheapertiskernel.md

@@ -658,15 +658,121 @@ An example of how to achieve this:
     series.
   - Use `gbp dch` to update changelog, tweak as necessary.
 
+### Updating the kernel from an upstream stable git branch
+
+The [Apertis release flow]( {{< ref "release-flow.md#apertis-release-flow" >}})
+stipulates that each Apertis release should include the latest mainline kernel
+LTS release.  Due to Debian's release cadence being approximately half that of
+Apertis', there are 2 Apertis releases for each Debian stable release and the
+latest LTS is not always packaged by Debian. As a result it is expected that
+Apertis will need to pull from the mainline kernel LTS tree to satisfy it's
+requirements. For example, Apertis v2020 ships with a newer version of the
+Linux kernel (5.4.x) than Debian Buster (4.9.x) on which it is based.
+
+In such cases, special care needs to be taken to update packages from their
+respective upstreams:
+
+- Using the GitLab web UI, check to ensure that the relevant update branch
+  exists, in the case of the Apertis `v2020` release, kernel updates should be
+  made on the `apertis/v2020-security` branch. Create the required branch if it
+  doesn't exist.
+- Clone the existing package from Apertis GitLab and checkout the relevant
+  branch:
+
+      $ git clone -b apertis/v2020-security git@gitlab.apertis.org:pkg/linux.git linux-apertis
+
+- Separately clone the Linux kernel LTS repository and checkout the relevant
+  stable branch:
+
+      $ git clone -b stable-linux-5.4.y git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git linux-stable
+
+- Create a `gbp pq` patch branch and switch back to normal branch. The patch
+  branch will be needed when rebasing the Debian patches:
+
+      $ cd linux-apertis
+      $ gbp pq import
+      $ gbp pq switch
+
+- Determine the latest stable release and derive the Apertis version to use. To
+  ensure collisions don't occur with any future Debian releases, we will mark
+  the release as the zeroth "Debian" release (`-0`) and first Apertis
+  pre-release (`~apertis1`):
+
+      $ KERNEL_RELEASE=`git -C ../linux-stable describe`
+      $ RELEASE="${KERNEL_RELEASE#v}-0~apertis1"
+
+- Add a changelog entry for newest `linux-5.4.y` kernel release (this is needed
+  to get `genorig.py` to use the right release):
+
+      $ DEBEMAIL="User Name <user@example.com>" dch -v "$RELEASE" ""
+      $ git add -f debian/changelog
+      $ git commit -s -m "Add changelog entry for update to $RELEASE"
+
+- Run `debian/bin/genorig.py` to generate debianised kernel source tarball:
+
+      $ debian/bin/genorig.py ../linux-stable
+
+- Import the updated source tarball:
+
+      $ gbp import-orig --upstream-branch=upstream/linux-5.4.y --debian-branch=apertis/v2020-security <path to orig tarball>
+
+- Rebase the Debian patches on the new kernel version:
+
+      $ gbp pq rebase
+
+  This may require some manual intervention following the normal git rebasing
+  process.
+
+- Export updated patch series:
+
+      $ gbp pq export
+
+- Tweak `debian/patches/series` file so that it retains the comments that `gbp
+  pq` wants to drop. If no patches have been dropped during rebase then:
+
+      $ git checkout debian/patches/series
+      $ git add -f debian/patches
+      $ git commit -s -m "Update the debian patches for $RELEASE update"
+
+- Update changelog to released state (set distribution to apertis), document
+  any patches that have been dropped as a result of the update and create new
+  commit:
+
+      $ dch -D apertis
+      $ git add -f debian/changelog
+      $ git commit -s -m "Release linux version $RELEASE"
+
+- Run `dpkg-buildpackage` to generate the debian packaging, this is needed to
+  use the tools to update the
+  [pristine-lfs branch]( {{< ref "component_structure.md" >}} ):
+
+      $ mkdir ../build
+      $ gbp buildpackage --git-ignore-new \
+          --git-debian-branch=apertis/v2020-security \
+          --git-prebuild='debian/rules debian/control || true' \
+          --git-export-dir='../build' \
+          --no-sign -us -S
+
+- Import the generated kernel tarball into pristine-lfs branch with
+  `import-tarballs`:
+
+      $ git clone git@gitlab.apertis.org:infrastructure/packaging-tools.git ../packaging-tools
+      $ ../packaging-tools/import-tarballs ../build/<kernel .dsc file>
+      $ git push origin pristine-lfs
+
+- Push kernel update to a branch to be reviewed:
+
+      $ git push origin apertis/v2020-security:wip/${GITLAB_USER}/${KERNEL_RELEASE}-kernel-update
+
 ### Version numbering
 
 The updated nature of the package is reflected in the version number
 given to the package and this will have an impact on the version number
 that should be assigned to the newly rebased tree (new upstream, plus or
 or more local changes). As an example will assume 3 local revisions have
-been made since the last rebase on `4.19.37-5co4`, following our
-previous example the version would expected to be `4.19.37-5co4foo3`,
-should a new Apertis release be made (`4.19.37-5co5`) and assuming that
+been made since the last rebase on `4.19.37-5+apertis4`, following our
+previous example the version would expected to be `4.19.37-5+apertis4foo3`,
+should a new Apertis release be made (`4.19.37-5+apertis5`) and assuming that
 the local changes are still needed, then the local version with these
 inclusions with constitute the first local release on top of the new
-upstream, thus becoming `4.19.37-5co5foo1`.
+upstream, thus becoming `4.19.37-5+apertis5foo1`.