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,6 +658,112 @@ 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