Bug#301011: #301011 - more verbose instructions on new upstream package

"Serafeim (Serafi) Zanikolas" <[email protected]> Wed, 13 May 2026 22:44:00 +0200

Newsgroups	gmane.linux.debian.devel.policy
Message-ID	<DIHUBB5B9N6J.3E7YH2QTNQ1NS__36206.8160598696$1778705145$gmane$org@debian.org>

hi Holger,

thanks for the quick feedback. new patch attached, which I believe addresses all
comments.

thanks,
serafi

0001-pkgs-add-a-section-with-a-checklist-for-new-upstream.patch (text/x-patch, 2.7 KB)

From 912e78f245e6eecf68beb7903841a09aeefe9173 Mon Sep 17 00:00:00 2001
From: "Serafeim (Serafi) Zanikolas" <[email protected]>
Date: Tue, 12 May 2026 22:52:09 +0200
Subject: [PATCH] pkgs: add a section with a checklist for new upstream
 versions. Closes #301011.

Based on suggestions from Brian Nelson <[email protected]>, edited for
freshness and brevity.
---
 source/pkgs.rst | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/source/pkgs.rst b/source/pkgs.rst
index bd48444..676ff51 100644
--- a/source/pkgs.rst
+++ b/source/pkgs.rst
@@ -553,6 +553,47 @@ the section is main, it should be omitted. The list of allowable
 subsections can be found in
 https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections\ .
 
+.. _new-upstream:
+
+New upstream versions
+================================================================================================================================
+
+To update a package for a new upstream release:
+
+1. Read the upstream changelog, NEWS, and whatever other documentation
+   they may have released with the new version.
+
+2. If possible, inspect the full diff between the old and new upstream sources,
+   potentially filtering out uninteresting parts using filterdiff (e.g.
+   ``filterdiff -x '*.po'``). If it's too big to review thoroughly, you can use
+   ``diffstat`` to get a feel for the scope and nature of the changes (and thus
+   where new bugs may appear), and to keep an eye for anything suspicious (e.g.
+   unexpected use of network or the apperance of dubious binary blobs).
+
+3. Port the old Debian packaging to the new version. This basically involves
+   incrementing the ``debian/changelog`` and merging ``debian/patches`` from the
+   old package to the new one.
+
+4. Check to see if any bugs have been fixed that are currently open in the BTS.
+   If they have been, close them in the ``debian/changelog``.
+
+5. If the patch/merge did not apply cleanly, figure out why. A patch may fail to
+   apply if it's already been applied in the new upstream release, or if the
+   upstream files the patch applies to have been substantially modified (or
+   deleted).
+
+6. If any changes were made to the build system (you'd know from steps 1 and 2),
+   update the ``debian/rules`` and ``debian/control`` build dependencies if
+   necessary.
+
+7. Build the new package in an isolated environment, e.g. using ``sbuild`` or
+   ``pbuilder``. This ensures that all required build dependencies are listed in
+   ``debian/control`` and eliminates the possibility of interference of any
+   third party packages in your system.
+
+8. Verify that the new package builds correctly and if so carry out the checks
+   in :ref:`_sanitycheck`.
+
 .. _bug-handling:
 
 Handling bugs
-- 
2.47.3

signature.asc (application/pgp-signature, 833 B)