From c3d2d337b8393e43a7c2c4d3813a5e2147a6b20b Mon Sep 17 00:00:00 2001
From: Martyn Welch <martyn.welch@collabora.com>
Date: Fri, 31 Mar 2023 12:36:09 +0100
Subject: [PATCH] Improve Apertis documentation of kernel version updates

Due to the metadata that we have committed into the Apertis kernel
repository, it is important that we take some extra steps when changing
the package version to ensure that the version in the metadata stays in
sync. Update the document to make these requirements clearer.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>
---
 debian/apertis/README.source | 56 ++++++++++++++++++++++++++++++------
 1 file changed, 47 insertions(+), 9 deletions(-)

diff --git a/debian/apertis/README.source b/debian/apertis/README.source
index 3c07d0a42ee..2bb48baad56 100644
--- a/debian/apertis/README.source
+++ b/debian/apertis/README.source
@@ -1,15 +1,53 @@
-Merging Upstream Changes
-========================
+Updating Debian Kernel Metadata
+===============================
 
 The Debian metadata used for the Linux kernel is a little more complex than
 that provided for most other packages, due to the large number of packages that
-are built from the source.  As a result of this complexity, merging upstream
-changes into our tree can be more challenging than with other components.
+are built from the source.  As a result of this complexity, updating the
+metadata can be more challenging than with other components, whether after
+merging upstream changes into our tree or needing to bump the version due to
+additional local changes.
 
-The process for the most part follows the guide for manually updating
-components from Debian (https://www.apertis.org/guides/component_guide/),
-however merging the metadata is far more efficiently achieved by using the
-tooling provided by the Debian kernel team than attempting to do this manually:
+
+Updating the kernel version
+---------------------------
+
+When updating the changelog with a new version, there are a host of other
+places where the version number also needs to be updated, which again is far
+more efficiently achieved by using the tooling provided.
+
+- After updating the changelog as normal, run the following script to
+  regenerate all the autogenerated files:
+
+      debian/apertis/update-metadata
+
+  This will automatically regenerate:
+
+  - debian/config.defines.dump
+  - debian/control
+  - debian/control.md5sum
+  - debian/rules.gen
+  - debian/*.bug-presubj
+  - debian/*.postinst
+  - debian/*.postrm
+  - debian/*.preinst
+  - debian/*.prerm
+  - debian/*.maintscript
+  - debian/*.lintian-overrides
+  - debian/build/version-info
+  - debian/tests/control
+
+- Commit these changes along with the change to the changelog.
+
+
+Merging Changes
+---------------
+
+When merging changes, the process for the most part follows the guide for
+manually updating components from Debian
+(https://www.apertis.org/guides/component_guide/), however merging the metadata
+is far more efficiently achieved by using the tooling provided by the Debian
+kernel team than attempting to do this manually.
 
 - Perform the manual merge steps as normal until `apertis-pkg-merge-updates`,
   at which time it is highly likely that you will need to fix some conflicts.
@@ -29,7 +67,6 @@ tooling provided by the Debian kernel team than attempting to do this manually:
 
   This will automatically regenerate:
 
-  - debian/rules.gen
   - debian/config.defines.dump
   - debian/control
   - debian/control.md5sum
@@ -41,6 +78,7 @@ tooling provided by the Debian kernel team than attempting to do this manually:
   - debian/*.prerm
   - debian/*.maintscript
   - debian/*.lintian-overrides
+  - debian/build/version-info
   - debian/tests/control
 
 - Fix other changes and continue merge as normal (without adding the changelog update).
-- 
GitLab