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

"Serafeim (Serafi) Zanikolas" <[email protected]> Tue, 12 May 2026 23:07:32 +0200

Newsgroups	gmane.linux.debian.devel.policy
Message-ID	<DIH06S4MZC08.28K28LH09D3LR__45482.3298308597$1778620050$gmane$org@debian.org>

tags 301011 + patch
thanks

hi,

please find attached a patch.

thanks,
serafi

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

From 7237b294009e5f43463ff238609cdc4f237ed2d2 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 | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/source/pkgs.rst b/source/pkgs.rst
index bd48444..488e87e 100644
--- a/source/pkgs.rst
+++ b/source/pkgs.rst
@@ -553,6 +553,45 @@ 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. Diff the old and new upstream sources (e.g. with ``diff -urN`` or ``git``
+   equivalent) to get a feel for the scope of the changes, where work is actively
+   being done (and thus where new bugs may appear), and also keep an eye out for
+   anything suspicious.
+
+3. Port the old Debian packaging to the new version.  This basically involves
+   merging ``debian/patches`` from the old package to the new one and incrementing
+   the ``debian/changelog``.
+
+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 (hopefully 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 a chroot, e.g. using ``pbuilder``. A chroot 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)