README.source: Document how to update the changelog for a new upstream version

1 files changed, 30 insertions, 0 deletions

diff --git a/debian/README.source b/debian/README.source
index 39894e003220..98569e08bb5b 100644
--- a/debian/README.source
+++ b/debian/README.source
@@ -53,6 +53,36 @@ unifdef packages installed.
    will usually fail due to conflicts with upstream changes.  You need
    to resolve those by dropping or refreshing patches.
 
+Recording updates in the changelog
+----------------------------------
+
+Upstream commits that we already cherry-picked and included in a
+previous package upload should not be mentioned, since they don't make
+any difference to the package.  Any other commits that fix a Debian
+bug report and/or a security issue with a CVE ID should always be
+listed, along with the (Closes: #nnnnnn) and/or (CVE-yyyy-nnnn)
+reference.
+
+Aside from those general rules:
+
+* For an upstream release candidate, don't attempt to list the changes
+
+* For a stable release by Linus, refer to the summary at
+  kernelnewbies.org, e.g. http://kernelnewbies.org/Linux_4.5
+
+* For a stable update, refer to the changelog on kernel.org, e.g.
+  https://www.kernel.org/pub/linux/kernel/v4.x/ChangeLog-4.5.1, and
+  list all changes that are relevant to our package and that fix bugs
+  that we would consider 'important' or higher severity
+
+  - The script debian/bin/stable-update.sh updates the changelog
+    version and inserts the list of changes (but it doesn't always
+    put it in the right place!).  It doesn't attempt to filter out
+    irrelevant or unimportant changes.
+
+  - The script debian/bin/ckt-stable-update.sh does the same for
+    stable updates by the Canonical Kernel Team.
+
 Applying patches to the Debian kernel tree
 ==========================================