From f7e816a2d0612e1b041a89ad3fd8e70231b12f56 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Mon, 9 Mar 2026 10:13:09 +1300 Subject: [PATCH 01/18] docs: create building section (package builds) --- .../{contributors/bug-fix => building}/build-packages-in-a-ppa.md | 0 .../{contributors/bug-fix => building}/build-packages-locally.rst | 0 .../{contributors/bug-fix => building}/install-built-packages.rst | 0 docs/{contributors/bug-fix => building}/run-package-tests.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename docs/{contributors/bug-fix => building}/build-packages-in-a-ppa.md (100%) rename docs/{contributors/bug-fix => building}/build-packages-locally.rst (100%) rename docs/{contributors/bug-fix => building}/install-built-packages.rst (100%) rename docs/{contributors/bug-fix => building}/run-package-tests.md (100%) diff --git a/docs/contributors/bug-fix/build-packages-in-a-ppa.md b/docs/building/build-packages-in-a-ppa.md similarity index 100% rename from docs/contributors/bug-fix/build-packages-in-a-ppa.md rename to docs/building/build-packages-in-a-ppa.md diff --git a/docs/contributors/bug-fix/build-packages-locally.rst b/docs/building/build-packages-locally.rst similarity index 100% rename from docs/contributors/bug-fix/build-packages-locally.rst rename to docs/building/build-packages-locally.rst diff --git a/docs/contributors/bug-fix/install-built-packages.rst b/docs/building/install-built-packages.rst similarity index 100% rename from docs/contributors/bug-fix/install-built-packages.rst rename to docs/building/install-built-packages.rst diff --git a/docs/contributors/bug-fix/run-package-tests.md b/docs/building/run-package-tests.md similarity index 100% rename from docs/contributors/bug-fix/run-package-tests.md rename to docs/building/run-package-tests.md From 8eb7e2f931d6909eb7f0ffa5f22b44af093d7d72 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Mon, 9 Mar 2026 10:13:26 +1300 Subject: [PATCH 02/18] docs: update documentation references --- docs/building/index.md | 11 +++++++++++ docs/contributors/bug-fix/index.md | 8 ++++---- docs/contributors/index.md | 9 +++++++++ docs/redirects.txt | 14 ++++++++------ 4 files changed, 32 insertions(+), 10 deletions(-) create mode 100644 docs/building/index.md diff --git a/docs/building/index.md b/docs/building/index.md new file mode 100644 index 000000000..5c8fc0bec --- /dev/null +++ b/docs/building/index.md @@ -0,0 +1,11 @@ +(building)= +# Building + +```{toctree} +:maxdepth: 1 + +Build packages in a PPA +Build packages locally +Install built packages +Run package tests +``` diff --git a/docs/contributors/bug-fix/index.md b/docs/contributors/bug-fix/index.md index ea133baf7..29c76863e 100644 --- a/docs/contributors/bug-fix/index.md +++ b/docs/contributors/bug-fix/index.md @@ -9,12 +9,12 @@ Get a new upstream version Extract packages -Install built packages +Install built packages Fix a bug in a package -Build packages in a PPA -Build packages locally +Build packages in a PPA +Build packages locally Propose changes -Run package tests +Run package tests ``` ## Checklists diff --git a/docs/contributors/index.md b/docs/contributors/index.md index 577f9dd7f..072576098 100644 --- a/docs/contributors/index.md +++ b/docs/contributors/index.md @@ -50,6 +50,15 @@ bug-fix/index ``` +## Building + +```{toctree} +:maxdepth: 1 + +/building/index +``` + + ## Patching ```{toctree} diff --git a/docs/redirects.txt b/docs/redirects.txt index a57b81a2d..1facc10c3 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -85,21 +85,23 @@ contributors/advanced/request-package-removal/ contributors/advanced/aa-request- tutorial/fix-bug/ contributors/bug-fix/ contributors/index-bug-fix/ contributors/bug-fix/ -contributors/bug-fix/build-packages/ contributors/bug-fix/build-packages-in-a-ppa/ -contributors/bug-fix/package-building/ contributors/bug-fix/build-packages-in-a-ppa/ +contributors/bug-fix/build-packages/ building/build-packages-in-a-ppa/ +contributors/bug-fix/package-building/ building/build-packages-in-a-ppa/ -how-to/build-packages/ contributors/bug-fix/build-packages-locally/ +how-to/build-packages/ building/build-packages-locally/ how-to/extract-packages/ contributors/bug-fix/extract-packages/ contributors/bug-fix/download-new-upstream-version/ contributors/bug-fix/get-a-new-upstream-version/ how-to/download-new-upstream-version/ contributors/bug-fix/get-a-new-upstream-version/ -how-to/install-built-packages/ contributors/bug-fix/install-built-packages/ +how-to/install-built-packages/ building/install-built-packages/ +contributors/bug-fix/install-built-packages/ building/install-built-packages/ how-to/propose-changes/ contributors/bug-fix/propose-changes/ -how-to/run-tests/ contributors/bug-fix/run-package-tests/ -contributors/bug-fix/package-tests/ contributors/bug-fix/run-package-tests/ +how-to/run-tests/ building/run-package-tests/ +contributors/bug-fix/package-tests/ building/run-package-tests/ +contributors/bug-fix/run-package-tests/ building/run-package-tests/ contributors/index-bug-triage/ contributors/bug-triage/ From a1ab82c5bf5b8ccf92f892866a290e45bc2dff70 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Mon, 9 Mar 2026 10:20:24 +1300 Subject: [PATCH 03/18] docs: create updating section --- .../patching => updating}/commit-changes.md | 0 .../get-a-new-upstream-version.rst | 0 docs/updating/index.md | 10 ++++++++++ .../patching => updating}/submit-a-merge-proposal.md | 0 4 files changed, 10 insertions(+) rename docs/{contributors/patching => updating}/commit-changes.md (100%) rename docs/{contributors/bug-fix => updating}/get-a-new-upstream-version.rst (100%) create mode 100644 docs/updating/index.md rename docs/{contributors/patching => updating}/submit-a-merge-proposal.md (100%) diff --git a/docs/contributors/patching/commit-changes.md b/docs/updating/commit-changes.md similarity index 100% rename from docs/contributors/patching/commit-changes.md rename to docs/updating/commit-changes.md diff --git a/docs/contributors/bug-fix/get-a-new-upstream-version.rst b/docs/updating/get-a-new-upstream-version.rst similarity index 100% rename from docs/contributors/bug-fix/get-a-new-upstream-version.rst rename to docs/updating/get-a-new-upstream-version.rst diff --git a/docs/updating/index.md b/docs/updating/index.md new file mode 100644 index 000000000..7c56d0846 --- /dev/null +++ b/docs/updating/index.md @@ -0,0 +1,10 @@ +(updating)= +# Updating + +```{toctree} +:maxdepth: 1 + +Get a new upstream version +Commit changes +Submit a merge proposal +``` diff --git a/docs/contributors/patching/submit-a-merge-proposal.md b/docs/updating/submit-a-merge-proposal.md similarity index 100% rename from docs/contributors/patching/submit-a-merge-proposal.md rename to docs/updating/submit-a-merge-proposal.md From ffd65930d6a1ba23bfcdc38d75cc8ddb19bf432f Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Mon, 9 Mar 2026 10:20:44 +1300 Subject: [PATCH 04/18] docs: update indices and redirects --- docs/contributors/bug-fix/index.md | 2 +- docs/contributors/index.md | 9 +++++++++ docs/contributors/patching/index.md | 4 ++-- docs/redirects.txt | 8 ++++---- 4 files changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/contributors/bug-fix/index.md b/docs/contributors/bug-fix/index.md index 29c76863e..a097f0af5 100644 --- a/docs/contributors/bug-fix/index.md +++ b/docs/contributors/bug-fix/index.md @@ -7,7 +7,7 @@ ```{toctree} :maxdepth: 1 -Get a new upstream version +Get a new upstream version Extract packages Install built packages Fix a bug in a package diff --git a/docs/contributors/index.md b/docs/contributors/index.md index 072576098..c3a4174d0 100644 --- a/docs/contributors/index.md +++ b/docs/contributors/index.md @@ -50,6 +50,15 @@ bug-fix/index ``` +## Updating + +```{toctree} +:maxdepth: 1 + +/updating/index +``` + + ## Building ```{toctree} diff --git a/docs/contributors/patching/index.md b/docs/contributors/patching/index.md index ea69afcfd..5df58cf08 100644 --- a/docs/contributors/patching/index.md +++ b/docs/contributors/patching/index.md @@ -7,7 +7,7 @@ Make changes to a package Manage patches Work with Debian patches -Commit changes -Submit a merge proposal +Commit changes +Submit a merge proposal Dual maintenance with Salsa and git-ubuntu ``` diff --git a/docs/redirects.txt b/docs/redirects.txt index 1facc10c3..953f8d815 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -92,8 +92,8 @@ how-to/build-packages/ building/build-packages-locally/ how-to/extract-packages/ contributors/bug-fix/extract-packages/ -contributors/bug-fix/download-new-upstream-version/ contributors/bug-fix/get-a-new-upstream-version/ -how-to/download-new-upstream-version/ contributors/bug-fix/get-a-new-upstream-version/ +contributors/bug-fix/download-new-upstream-version/ updating/get-a-new-upstream-version/ +how-to/download-new-upstream-version/ updating/get-a-new-upstream-version/ how-to/install-built-packages/ building/install-built-packages/ contributors/bug-fix/install-built-packages/ building/install-built-packages/ @@ -132,7 +132,7 @@ how-to/upload-packages-to-ppa/ contributors/new-package/upload-packages-to-a-ppa contributors/index-patching/ contributors/patching/ -contributors/patching/committing-changes/ contributors/patching/commit-changes/ +contributors/patching/committing-changes/ updating/commit-changes/ contributors/patching/salsa-dual-maintenance/ contributors/patching/dual-maintenance-with-salsa-and-git-ubuntu/ @@ -142,7 +142,7 @@ tutorial/make-changes-to-package/ contributors/patching/make-changes-to-a-packag contributors/patching/patch-management/ contributors/patching/manage-patches/ how-to/patch-management/ contributors/patching/manage-patches/ -contributors/patching/merge-proposal/ contributors/patching/submit-a-merge-proposal/ +contributors/patching/merge-proposal/ updating/submit-a-merge-proposal/ contributors/index-qa-and-testing/ contributors/qa-and-testing/ From c1b81a12566db2ef91ffe02fbb45f7543d985812 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Mon, 9 Mar 2026 10:33:37 +1300 Subject: [PATCH 05/18] docs: move patching -> updating --- docs/contributors/patching/index.md | 13 ------------- .../patching => updating}/configure.bash | 0 .../dual-maintenance-with-salsa-and-git-ubuntu.md | 0 docs/updating/index.md | 5 +++++ .../make-changes-to-a-package.rst | 0 .../patching => updating}/manage-patches.rst | 0 .../work-with-debian-patches.md | 0 7 files changed, 5 insertions(+), 13 deletions(-) delete mode 100644 docs/contributors/patching/index.md rename docs/{contributors/patching => updating}/configure.bash (100%) rename docs/{contributors/patching => updating}/dual-maintenance-with-salsa-and-git-ubuntu.md (100%) rename docs/{contributors/patching => updating}/make-changes-to-a-package.rst (100%) rename docs/{contributors/patching => updating}/manage-patches.rst (100%) rename docs/{contributors/patching => updating}/work-with-debian-patches.md (100%) diff --git a/docs/contributors/patching/index.md b/docs/contributors/patching/index.md deleted file mode 100644 index 5df58cf08..000000000 --- a/docs/contributors/patching/index.md +++ /dev/null @@ -1,13 +0,0 @@ -(patching)= -# Patching - -```{toctree} -:maxdepth: 1 - -Make changes to a package -Manage patches -Work with Debian patches -Commit changes -Submit a merge proposal -Dual maintenance with Salsa and git-ubuntu -``` diff --git a/docs/contributors/patching/configure.bash b/docs/updating/configure.bash similarity index 100% rename from docs/contributors/patching/configure.bash rename to docs/updating/configure.bash diff --git a/docs/contributors/patching/dual-maintenance-with-salsa-and-git-ubuntu.md b/docs/updating/dual-maintenance-with-salsa-and-git-ubuntu.md similarity index 100% rename from docs/contributors/patching/dual-maintenance-with-salsa-and-git-ubuntu.md rename to docs/updating/dual-maintenance-with-salsa-and-git-ubuntu.md diff --git a/docs/updating/index.md b/docs/updating/index.md index 7c56d0846..b97f264ac 100644 --- a/docs/updating/index.md +++ b/docs/updating/index.md @@ -1,10 +1,15 @@ (updating)= +(patching)= # Updating ```{toctree} :maxdepth: 1 Get a new upstream version +Make changes to a package +Manage patches +Work with Debian patches Commit changes Submit a merge proposal +Dual maintenance with Salsa and git-ubuntu ``` diff --git a/docs/contributors/patching/make-changes-to-a-package.rst b/docs/updating/make-changes-to-a-package.rst similarity index 100% rename from docs/contributors/patching/make-changes-to-a-package.rst rename to docs/updating/make-changes-to-a-package.rst diff --git a/docs/contributors/patching/manage-patches.rst b/docs/updating/manage-patches.rst similarity index 100% rename from docs/contributors/patching/manage-patches.rst rename to docs/updating/manage-patches.rst diff --git a/docs/contributors/patching/work-with-debian-patches.md b/docs/updating/work-with-debian-patches.md similarity index 100% rename from docs/contributors/patching/work-with-debian-patches.md rename to docs/updating/work-with-debian-patches.md From 49dede4150afae61fcdee7ae643ad8cfa324eb8c Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Mon, 9 Mar 2026 10:33:48 +1300 Subject: [PATCH 06/18] docs: update redirects and indices --- docs/contributors/index.md | 7 ------- docs/redirects.txt | 13 +++++++------ 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/contributors/index.md b/docs/contributors/index.md index c3a4174d0..88d7f2bf7 100644 --- a/docs/contributors/index.md +++ b/docs/contributors/index.md @@ -68,13 +68,6 @@ bug-fix/index ``` -## Patching - -```{toctree} -:maxdepth: 1 - -patching/index -``` ## Merging diff --git a/docs/redirects.txt b/docs/redirects.txt index 953f8d815..af0d2cb4e 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -130,17 +130,18 @@ contributors/new-package/request-sru/ contributors/new-package/request-an-sru/ contributors/new-package/upload-packages-to-ppa/ contributors/new-package/upload-packages-to-a-ppa/ how-to/upload-packages-to-ppa/ contributors/new-package/upload-packages-to-a-ppa/ -contributors/index-patching/ contributors/patching/ +contributors/index-patching/ updating/ +contributors/patching/ updating/ contributors/patching/committing-changes/ updating/commit-changes/ -contributors/patching/salsa-dual-maintenance/ contributors/patching/dual-maintenance-with-salsa-and-git-ubuntu/ +contributors/patching/salsa-dual-maintenance/ updating/dual-maintenance-with-salsa-and-git-ubuntu/ -contributors/patching/make-changes-to-package/ contributors/patching/make-changes-to-a-package/ -tutorial/make-changes-to-package/ contributors/patching/make-changes-to-a-package/ +contributors/patching/make-changes-to-package/ updating/make-changes-to-a-package/ +tutorial/make-changes-to-package/ updating/make-changes-to-a-package/ -contributors/patching/patch-management/ contributors/patching/manage-patches/ -how-to/patch-management/ contributors/patching/manage-patches/ +contributors/patching/patch-management/ updating/manage-patches/ +how-to/patch-management/ updating/manage-patches/ contributors/patching/merge-proposal/ updating/submit-a-merge-proposal/ From 4175f67bc42a4038b99025552024a5556553b5ac Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Mon, 9 Mar 2026 10:36:29 +1300 Subject: [PATCH 07/18] docs: move extract-packages under updating --- docs/{contributors/bug-fix => updating}/extract-packages.rst | 0 docs/updating/index.md | 1 + 2 files changed, 1 insertion(+) rename docs/{contributors/bug-fix => updating}/extract-packages.rst (100%) diff --git a/docs/contributors/bug-fix/extract-packages.rst b/docs/updating/extract-packages.rst similarity index 100% rename from docs/contributors/bug-fix/extract-packages.rst rename to docs/updating/extract-packages.rst diff --git a/docs/updating/index.md b/docs/updating/index.md index b97f264ac..873a022ce 100644 --- a/docs/updating/index.md +++ b/docs/updating/index.md @@ -6,6 +6,7 @@ :maxdepth: 1 Get a new upstream version +Extract packages Make changes to a package Manage patches Work with Debian patches From 53d93fc217cde0307fe088555c7273e2f0804346 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Mon, 9 Mar 2026 10:36:38 +1300 Subject: [PATCH 08/18] docs: update indices --- docs/contributors/bug-fix/index.md | 2 +- docs/redirects.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributors/bug-fix/index.md b/docs/contributors/bug-fix/index.md index a097f0af5..057ebd097 100644 --- a/docs/contributors/bug-fix/index.md +++ b/docs/contributors/bug-fix/index.md @@ -8,7 +8,7 @@ :maxdepth: 1 Get a new upstream version -Extract packages +Extract packages Install built packages Fix a bug in a package Build packages in a PPA diff --git a/docs/redirects.txt b/docs/redirects.txt index af0d2cb4e..32d2bffd7 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -90,7 +90,7 @@ contributors/bug-fix/package-building/ building/build-packages-in-a-ppa/ how-to/build-packages/ building/build-packages-locally/ -how-to/extract-packages/ contributors/bug-fix/extract-packages/ +how-to/extract-packages/ updating/extract-packages/ contributors/bug-fix/download-new-upstream-version/ updating/get-a-new-upstream-version/ how-to/download-new-upstream-version/ updating/get-a-new-upstream-version/ From e191a3a3bbb6c131f7692ca98e38fa1be9cd742c Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Mon, 9 Mar 2026 10:38:25 +1300 Subject: [PATCH 09/18] docs: move docs/updating -> docs/contributors/updating --- docs/contributors/bug-fix/index.md | 4 ++-- docs/contributors/index.md | 2 +- .../updating/commit-changes.md | 0 .../updating/configure.bash | 0 ...l-maintenance-with-salsa-and-git-ubuntu.md | 0 .../updating/extract-packages.rst | 0 .../updating/get-a-new-upstream-version.rst | 0 docs/{ => contributors}/updating/index.md | 0 .../updating/make-changes-to-a-package.rst | 0 .../updating/manage-patches.rst | 0 .../updating/submit-a-merge-proposal.md | 0 .../updating/work-with-debian-patches.md | 0 docs/redirects.txt | 24 +++++++++---------- 13 files changed, 15 insertions(+), 15 deletions(-) rename docs/{ => contributors}/updating/commit-changes.md (100%) rename docs/{ => contributors}/updating/configure.bash (100%) rename docs/{ => contributors}/updating/dual-maintenance-with-salsa-and-git-ubuntu.md (100%) rename docs/{ => contributors}/updating/extract-packages.rst (100%) rename docs/{ => contributors}/updating/get-a-new-upstream-version.rst (100%) rename docs/{ => contributors}/updating/index.md (100%) rename docs/{ => contributors}/updating/make-changes-to-a-package.rst (100%) rename docs/{ => contributors}/updating/manage-patches.rst (100%) rename docs/{ => contributors}/updating/submit-a-merge-proposal.md (100%) rename docs/{ => contributors}/updating/work-with-debian-patches.md (100%) diff --git a/docs/contributors/bug-fix/index.md b/docs/contributors/bug-fix/index.md index 057ebd097..305dda555 100644 --- a/docs/contributors/bug-fix/index.md +++ b/docs/contributors/bug-fix/index.md @@ -7,8 +7,8 @@ ```{toctree} :maxdepth: 1 -Get a new upstream version -Extract packages +Get a new upstream version +Extract packages Install built packages Fix a bug in a package Build packages in a PPA diff --git a/docs/contributors/index.md b/docs/contributors/index.md index 88d7f2bf7..7c9d698ec 100644 --- a/docs/contributors/index.md +++ b/docs/contributors/index.md @@ -55,7 +55,7 @@ bug-fix/index ```{toctree} :maxdepth: 1 -/updating/index +updating/index ``` diff --git a/docs/updating/commit-changes.md b/docs/contributors/updating/commit-changes.md similarity index 100% rename from docs/updating/commit-changes.md rename to docs/contributors/updating/commit-changes.md diff --git a/docs/updating/configure.bash b/docs/contributors/updating/configure.bash similarity index 100% rename from docs/updating/configure.bash rename to docs/contributors/updating/configure.bash diff --git a/docs/updating/dual-maintenance-with-salsa-and-git-ubuntu.md b/docs/contributors/updating/dual-maintenance-with-salsa-and-git-ubuntu.md similarity index 100% rename from docs/updating/dual-maintenance-with-salsa-and-git-ubuntu.md rename to docs/contributors/updating/dual-maintenance-with-salsa-and-git-ubuntu.md diff --git a/docs/updating/extract-packages.rst b/docs/contributors/updating/extract-packages.rst similarity index 100% rename from docs/updating/extract-packages.rst rename to docs/contributors/updating/extract-packages.rst diff --git a/docs/updating/get-a-new-upstream-version.rst b/docs/contributors/updating/get-a-new-upstream-version.rst similarity index 100% rename from docs/updating/get-a-new-upstream-version.rst rename to docs/contributors/updating/get-a-new-upstream-version.rst diff --git a/docs/updating/index.md b/docs/contributors/updating/index.md similarity index 100% rename from docs/updating/index.md rename to docs/contributors/updating/index.md diff --git a/docs/updating/make-changes-to-a-package.rst b/docs/contributors/updating/make-changes-to-a-package.rst similarity index 100% rename from docs/updating/make-changes-to-a-package.rst rename to docs/contributors/updating/make-changes-to-a-package.rst diff --git a/docs/updating/manage-patches.rst b/docs/contributors/updating/manage-patches.rst similarity index 100% rename from docs/updating/manage-patches.rst rename to docs/contributors/updating/manage-patches.rst diff --git a/docs/updating/submit-a-merge-proposal.md b/docs/contributors/updating/submit-a-merge-proposal.md similarity index 100% rename from docs/updating/submit-a-merge-proposal.md rename to docs/contributors/updating/submit-a-merge-proposal.md diff --git a/docs/updating/work-with-debian-patches.md b/docs/contributors/updating/work-with-debian-patches.md similarity index 100% rename from docs/updating/work-with-debian-patches.md rename to docs/contributors/updating/work-with-debian-patches.md diff --git a/docs/redirects.txt b/docs/redirects.txt index 32d2bffd7..2a0d7dd39 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -90,10 +90,10 @@ contributors/bug-fix/package-building/ building/build-packages-in-a-ppa/ how-to/build-packages/ building/build-packages-locally/ -how-to/extract-packages/ updating/extract-packages/ +how-to/extract-packages/ contributors/updating/extract-packages/ -contributors/bug-fix/download-new-upstream-version/ updating/get-a-new-upstream-version/ -how-to/download-new-upstream-version/ updating/get-a-new-upstream-version/ +contributors/bug-fix/download-new-upstream-version/ contributors/updating/get-a-new-upstream-version/ +how-to/download-new-upstream-version/ contributors/updating/get-a-new-upstream-version/ how-to/install-built-packages/ building/install-built-packages/ contributors/bug-fix/install-built-packages/ building/install-built-packages/ @@ -130,20 +130,20 @@ contributors/new-package/request-sru/ contributors/new-package/request-an-sru/ contributors/new-package/upload-packages-to-ppa/ contributors/new-package/upload-packages-to-a-ppa/ how-to/upload-packages-to-ppa/ contributors/new-package/upload-packages-to-a-ppa/ -contributors/index-patching/ updating/ -contributors/patching/ updating/ +contributors/index-patching/ contributors/updating/ +contributors/patching/ contributors/updating/ -contributors/patching/committing-changes/ updating/commit-changes/ +contributors/patching/committing-changes/ contributors/updating/commit-changes/ -contributors/patching/salsa-dual-maintenance/ updating/dual-maintenance-with-salsa-and-git-ubuntu/ +contributors/patching/salsa-dual-maintenance/ contributors/updating/dual-maintenance-with-salsa-and-git-ubuntu/ -contributors/patching/make-changes-to-package/ updating/make-changes-to-a-package/ -tutorial/make-changes-to-package/ updating/make-changes-to-a-package/ +contributors/patching/make-changes-to-package/ contributors/updating/make-changes-to-a-package/ +tutorial/make-changes-to-package/ contributors/updating/make-changes-to-a-package/ -contributors/patching/patch-management/ updating/manage-patches/ -how-to/patch-management/ updating/manage-patches/ +contributors/patching/patch-management/ contributors/updating/manage-patches/ +how-to/patch-management/ contributors/updating/manage-patches/ -contributors/patching/merge-proposal/ updating/submit-a-merge-proposal/ +contributors/patching/merge-proposal/ contributors/updating/submit-a-merge-proposal/ contributors/index-qa-and-testing/ contributors/qa-and-testing/ From 73978dda95bc1cb2882462e8c25d66bdf262261d Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Mon, 9 Mar 2026 10:52:41 +1300 Subject: [PATCH 10/18] docs: resolute duplicates in merge sections --- .../merging/git-ubuntu-merge-proposal.md | 76 ++++++------------ .../updating/submit-a-merge-proposal.md | 78 +++++++++++++++++++ 2 files changed, 103 insertions(+), 51 deletions(-) diff --git a/docs/contributors/merging/git-ubuntu-merge-proposal.md b/docs/contributors/merging/git-ubuntu-merge-proposal.md index 2a00a57aa..608d78b59 100644 --- a/docs/contributors/merging/git-ubuntu-merge-proposal.md +++ b/docs/contributors/merging/git-ubuntu-merge-proposal.md @@ -29,7 +29,8 @@ Extra: ## Open a merge proposal -Use the {command}`submit` command of {manpage}`git-ubuntu(1)`: +See {ref}`submit-mp-open` in {ref}`how-to-submit-a-merge-proposal` for the +full instructions. For merges, use `--target-branch debian/sid`: ```none $ git ubuntu submit --reviewer $REVIEWER --target-branch debian/sid @@ -38,33 +39,8 @@ If it looks OK, please move it to the 'Needs Review' state. ``` :::{note} -Git branches with `%` in their name don't work. Use something like `_`. -::: - -Set `--reviewer` to the team (or user) on Launchpad that should look at your change -- by default it is `--reviewer ubuntu-sponsors`. - -* If you do not have upload rights for this package, use `ubuntu-sponsors` here. That adds your Merge Proposal to the - [Ubuntu sponsoring queue](http://sponsoring-reports.ubuntu.com/general.html), so people with upload rights for that package may eventually review it for you. - -* To notify a specific team, use, e.g. `canonical-foundations`, `canonical-public-cloud`, or `ubuntu-server`. - -To avoid having to specify the `--reviewer` flag, configure the reviewers for {command}`git-ubuntu`. Include a section like the following either globally in `~/.gitconfig`, or in individual repositories in `.git/config`: - -```ini -[gitubuntu.submit] - defaultReviewer = , \ - , \ - -``` - -The equivalent `git config` command is: - -```none -$ git config [--global] gitubuntu.submit.defaultReviewer -``` - -:::{note} -Using a target branch of `debian/sid` may seem wrong, but is a workaround for {lpbug}`1976112`. +Using a target branch of `debian/sid` may seem wrong, but is a workaround for +{lpbug}`1976112`. ::: If this fails, {ref}`do it manually `. @@ -73,41 +49,39 @@ If this fails, {ref}`do it manually `. (merge-update-the-merge-proposal)= ## Update the merge proposal -* Link the PPA. +See {ref}`submit-mp-prepare-description` and {ref}`submit-mp-open` in +{ref}`how-to-submit-a-merge-proposal` for guidance on writing the description +and linking your PPA. + +When adding a comment to help the reviewer, include: -* Add any other info (as a comment) that can help the reviewer. +* a link to the PPA +* test steps and results - Example: +Example: - ```none - PPA: https://launchpad.net/~kstenerud/+archive/ubuntu/disco-at-merge-1802914 +```none +PPA: https://launchpad.net/~kstenerud/+archive/ubuntu/disco-at-merge-1802914 - Basic test: - $ echo "echo abc >test.txt" | at now + 1 minute && sleep 1m && cat test.txt && rm test.txt +Basic test: +$ echo "echo abc >test.txt" | at now + 1 minute && sleep 1m && cat test.txt && rm test.txt - Package tests: - This package contains no tests. - ``` +Package tests: +This package contains no tests. +``` (merge-open-the-review)= ## Open the review -Change the MP status from {guilabel}`work in progress` to {guilabel}`needs review`. +Change the MP status from {guilabel}`work in progress` to +{guilabel}`needs review`. + +For sponsorship options, see {ref}`submit-mp-get-sponsorship` in +{ref}`how-to-submit-a-merge-proposal`. (merge-follow-the-migration)= ## Follow the migration -Once the merge proposal goes through, you must follow the package to make sure it gets to its destination. - - -(merge-package-tests)= -### Package tests - -The results from the latest package tests are published for each Ubuntu release. For example: [`autopkgtest.ubuntu.com/packages/o/openssh/questing/amd64`](https://autopkgtest.ubuntu.com/packages/o/openssh/questing/amd64). See {ref}`automatic-package-testing-autopkgtest`. - - -(merge-proposed-migration)= -### Proposed migration +See {ref}`submit-mp-follow-migration` in {ref}`how-to-submit-a-merge-proposal`. -The status of all packages is available from the [Ubuntu archive](https://ubuntu-archive-team.ubuntu.com/proposed-migration/) or one of its subdirectories. The top level directory is for the current dev release. Previous releases are in subdirectories. See {ref}`proposed-migration`. diff --git a/docs/contributors/updating/submit-a-merge-proposal.md b/docs/contributors/updating/submit-a-merge-proposal.md index 0fbc1e669..b7b853494 100644 --- a/docs/contributors/updating/submit-a-merge-proposal.md +++ b/docs/contributors/updating/submit-a-merge-proposal.md @@ -14,6 +14,7 @@ You do not have upload rights * See {ref}`how-to-find-a-sponsor` for guidance on how to get your upload sponsored. +(submit-mp-prepare-description)= ## Prepare a description The description is free-form, but should contain everything you did. Let the @@ -62,8 +63,60 @@ autopkgtest [11:15:09]: @@@@@@@@@@@@@@@@@@@@ summary postfix PASS ``` +(submit-mp-open)= ## Open the merge proposal +### Using `git-ubuntu` + +Use the {command}`submit` command of {manpage}`git-ubuntu(1)`: + +```none +$ git ubuntu submit --reviewer $REVIEWER --target-branch ubuntu/devel +Your merge proposal is now available at: https://code.launchpad.net/~kstenerud/ubuntu/+source/at/+git/at/+merge/358655 +If it looks OK, please move it to the 'Needs Review' state. +``` + +:::{note} +Git branches with `%` in their name don't work. Use something like `_`. +::: + +Set `--reviewer` to the team (or user) on Launchpad that should look at your +change — by default it is `--reviewer ubuntu-sponsors`. + +* If you do not have upload rights for this package, use `ubuntu-sponsors`. + That adds your Merge Proposal to the + [Ubuntu sponsoring queue](http://sponsoring-reports.ubuntu.com/general.html), + so people with upload rights for that package may eventually review it for + you. + +* To notify a specific team, use, e.g. `canonical-foundations`, + `canonical-public-cloud`, or `ubuntu-server`. + +To avoid having to specify the `--reviewer` flag, configure the reviewers for +{command}`git-ubuntu`. Include a section like the following either globally in +`~/.gitconfig`, or in individual repositories in `.git/config`: + +```ini +[gitubuntu.submit] + defaultReviewer = , \ + , \ + +``` + +The equivalent `git config` command is: + +```none +$ git config [--global] gitubuntu.submit.defaultReviewer +``` + +:::{note} +Using a target branch of `debian/sid` may seem wrong, but is a workaround for +{lpbug}`1976112`. +::: + + +### Using the Launchpad web UI + You'll need to have a branch set up for your package. The following steps will create the merge proposal: @@ -92,6 +145,7 @@ You'll get a merge proposal [page like this](https://code.launchpad.net/~kstenerud/ubuntu/+source/postfix/+git/postfix/+merge/353267). + ## The second reviewer ```{important} @@ -149,6 +203,7 @@ It only lists core, so the second reviewer is * Type in `canonical-server-core-reviewers`. +(submit-mp-get-sponsorship)= ## Get sponsorship Before {ref}`asking your sponsor to upload `, it is wise to verify @@ -178,6 +233,7 @@ Please sponsor this MP. Git commit: 566d8c9eff6a13c25c2ef5f5d9e176f49c52a3b4 The sponsor will tag the upload and `dput` it to where it belongs. +(submit-mp-retire)= ## Retire a merge proposal If a merge proposal should no longer land as-is, you have four options: @@ -210,3 +266,25 @@ Delete the merge proposal Note that this might be necessary for appropriateness or legal reasons, but normally we prefer to use one of the other options since retaining the history of what happened may be useful in the future. + + +(submit-mp-follow-migration)= +## Follow the migration + +Once the merge proposal goes through, you must follow the package to make sure +it gets to its destination. +The status of all packages is available from the +[Ubuntu archive](https://ubuntu-archive-team.ubuntu.com/proposed-migration/) +or one of its subdirectories. The top level directory is for the current dev +release. Previous releases are in subdirectories. +See {ref}`proposed-migration`. + + +### Package tests + +The results from the latest package tests are published for each Ubuntu +release. For example: +[`autopkgtest.ubuntu.com/packages/o/openssh/questing/amd64`](https://autopkgtest.ubuntu.com/packages/o/openssh/questing/amd64). +See {ref}`automatic-package-testing-autopkgtest`. + + From 7acbbaa594a993a81cf57f6c8962ed05cec183da Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Wed, 25 Mar 2026 17:29:36 +1300 Subject: [PATCH 11/18] docs: move building -> contributors/building --- docs/contributors/bug-fix/index.md | 8 ++++---- .../building/build-packages-in-a-ppa.md | 0 .../building/build-packages-locally.rst | 0 docs/{ => contributors}/building/index.md | 0 .../building/install-built-packages.rst | 0 .../building/run-package-tests.md | 0 docs/contributors/index.md | 2 +- docs/redirects.txt | 16 ++++++++-------- 8 files changed, 13 insertions(+), 13 deletions(-) rename docs/{ => contributors}/building/build-packages-in-a-ppa.md (100%) rename docs/{ => contributors}/building/build-packages-locally.rst (100%) rename docs/{ => contributors}/building/index.md (100%) rename docs/{ => contributors}/building/install-built-packages.rst (100%) rename docs/{ => contributors}/building/run-package-tests.md (100%) diff --git a/docs/contributors/bug-fix/index.md b/docs/contributors/bug-fix/index.md index 305dda555..fb58b3517 100644 --- a/docs/contributors/bug-fix/index.md +++ b/docs/contributors/bug-fix/index.md @@ -9,12 +9,12 @@ Get a new upstream version Extract packages -Install built packages +Install built packages Fix a bug in a package -Build packages in a PPA -Build packages locally +Build packages in a PPA +Build packages locally Propose changes -Run package tests +Run package tests ``` ## Checklists diff --git a/docs/building/build-packages-in-a-ppa.md b/docs/contributors/building/build-packages-in-a-ppa.md similarity index 100% rename from docs/building/build-packages-in-a-ppa.md rename to docs/contributors/building/build-packages-in-a-ppa.md diff --git a/docs/building/build-packages-locally.rst b/docs/contributors/building/build-packages-locally.rst similarity index 100% rename from docs/building/build-packages-locally.rst rename to docs/contributors/building/build-packages-locally.rst diff --git a/docs/building/index.md b/docs/contributors/building/index.md similarity index 100% rename from docs/building/index.md rename to docs/contributors/building/index.md diff --git a/docs/building/install-built-packages.rst b/docs/contributors/building/install-built-packages.rst similarity index 100% rename from docs/building/install-built-packages.rst rename to docs/contributors/building/install-built-packages.rst diff --git a/docs/building/run-package-tests.md b/docs/contributors/building/run-package-tests.md similarity index 100% rename from docs/building/run-package-tests.md rename to docs/contributors/building/run-package-tests.md diff --git a/docs/contributors/index.md b/docs/contributors/index.md index 7c9d698ec..abd828594 100644 --- a/docs/contributors/index.md +++ b/docs/contributors/index.md @@ -64,7 +64,7 @@ updating/index ```{toctree} :maxdepth: 1 -/building/index +/contributors/building/index ``` diff --git a/docs/redirects.txt b/docs/redirects.txt index 2a0d7dd39..f31fa6999 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -85,23 +85,23 @@ contributors/advanced/request-package-removal/ contributors/advanced/aa-request- tutorial/fix-bug/ contributors/bug-fix/ contributors/index-bug-fix/ contributors/bug-fix/ -contributors/bug-fix/build-packages/ building/build-packages-in-a-ppa/ -contributors/bug-fix/package-building/ building/build-packages-in-a-ppa/ +contributors/bug-fix/build-packages/ contributors/building/build-packages-in-a-ppa/ +contributors/bug-fix/package-building/ contributors/building/build-packages-in-a-ppa/ -how-to/build-packages/ building/build-packages-locally/ +how-to/build-packages/ contributors/building/build-packages-locally/ how-to/extract-packages/ contributors/updating/extract-packages/ contributors/bug-fix/download-new-upstream-version/ contributors/updating/get-a-new-upstream-version/ how-to/download-new-upstream-version/ contributors/updating/get-a-new-upstream-version/ -how-to/install-built-packages/ building/install-built-packages/ -contributors/bug-fix/install-built-packages/ building/install-built-packages/ +how-to/install-built-packages/ contributors/building/install-built-packages/ +contributors/bug-fix/install-built-packages/ contributors/building/install-built-packages/ how-to/propose-changes/ contributors/bug-fix/propose-changes/ -how-to/run-tests/ building/run-package-tests/ -contributors/bug-fix/package-tests/ building/run-package-tests/ -contributors/bug-fix/run-package-tests/ building/run-package-tests/ +how-to/run-tests/ contributors/building/run-package-tests/ +contributors/bug-fix/package-tests/ contributors/building/run-package-tests/ +contributors/bug-fix/run-package-tests/ contributors/building/run-package-tests/ contributors/index-bug-triage/ contributors/bug-triage/ From 6ec482687ab0cc17f1aa042fe8d148aced985dd7 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Wed, 25 Mar 2026 19:00:19 +1300 Subject: [PATCH 12/18] docs: split bixing a bug into several articles - split fix-bug-in-a-package - referenced building and updating sections - renamed proposing-a-change to bugfixng-workflow --- docs/contributors/bug-fix/apply-the-fix.md | 60 ++ ...ose-changes.rst => bugfixing-workflow.rst} | 8 +- .../bug-fix/check-if-is-it-already-fixed.md | 255 ++++++ docs/contributors/bug-fix/evalute-the-bug.md | 152 ++++ .../bug-fix/fix-a-bug-in-a-package.md | 796 ------------------ docs/contributors/bug-fix/index.md | 34 +- .../bug-fix/once-the-fix-is-accepted.md | 77 ++ .../bug-fix/update-the-bug-report.md | 132 +++ docs/contributors/bug-fix/validate-the-fix.md | 60 ++ docs/contributors/building/index.md | 3 + 10 files changed, 768 insertions(+), 809 deletions(-) create mode 100644 docs/contributors/bug-fix/apply-the-fix.md rename docs/contributors/bug-fix/{propose-changes.rst => bugfixing-workflow.rst} (97%) create mode 100644 docs/contributors/bug-fix/check-if-is-it-already-fixed.md create mode 100644 docs/contributors/bug-fix/evalute-the-bug.md delete mode 100644 docs/contributors/bug-fix/fix-a-bug-in-a-package.md create mode 100644 docs/contributors/bug-fix/once-the-fix-is-accepted.md create mode 100644 docs/contributors/bug-fix/update-the-bug-report.md create mode 100644 docs/contributors/bug-fix/validate-the-fix.md diff --git a/docs/contributors/bug-fix/apply-the-fix.md b/docs/contributors/bug-fix/apply-the-fix.md new file mode 100644 index 000000000..aad8f87a6 --- /dev/null +++ b/docs/contributors/bug-fix/apply-the-fix.md @@ -0,0 +1,60 @@ +## Apply the fix + +Whether the bug fix originates from an upstream project or your own work, +changes must be managed via patches: +- `debian/patches/`: This directory, located at the root of the package repository, stores the patch files themselves. +- `debian/patches/series`: This file defines the specific order in which the patches should be applied. +- `debian/changelog`: This file tracks the history of changes made to the package over time. + +In our workflow, we use `git-ubuntu` to manage and apply these changes to packages. + +### Step 1: Assign the task to yourself + +First, going back to our [example case](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470) + +Go to the task (row) that starts with "bionic" and assign the task to yourself. + +Switch the status to "in progress" using the yellow pencil icons. + + +### Step 2: Clone the package (if you haven't already) + +Find the repository name: + +```none +$ apt-cache show postfix | grep Source: +``` + +In this case, there is no Source field, so we just use `postfix`. + +```none +$ git ubuntu clone postfix postfix-gu +$ cd postfix-gu +``` + + +### Step 3: Make a branch based on the appropriate Ubuntu branch + +The affected version of `postfix` is in Bionic, so we branch from +`bionic-devel`. It helps to use a descriptive branch name. + +```none +$ git checkout pkg/ubuntu/bionic-devel -b postfix-sru-lp1753470-segfault-bionic +``` + + +### Step 4: Make a patch to fix the issue (maybe) + +If the only changes you made are within the `debian/` sub-directory, you don't +need a patchfile, and can skip this step. + +On the other hand, if you've made changes to the upstream code (anything +outside of the `debian/` directory), you'll need to generate a patch in +`debian/patches`. + +For instructions, see {ref}`how-to-work-with-debian-patches`. + + +### Step 5: Commit the patch + +See {ref}`how-to-commit-changes`. diff --git a/docs/contributors/bug-fix/propose-changes.rst b/docs/contributors/bug-fix/bugfixing-workflow.rst similarity index 97% rename from docs/contributors/bug-fix/propose-changes.rst rename to docs/contributors/bug-fix/bugfixing-workflow.rst index fd9756559..dff7deab9 100644 --- a/docs/contributors/bug-fix/propose-changes.rst +++ b/docs/contributors/bug-fix/bugfixing-workflow.rst @@ -1,9 +1,9 @@ -.. _how-to-propose-changes: +.. _bugfixing-workflow: -How to propose changes -====================== +Bugfixing workflow +================== -This guide walks through the process for proposing changes to Ubuntu. When you find a problem, obtain the code, work on a solution, test the fix, push your changes to :term:`Launchpad`, and request a review and merge. +This guide walks through the process for fixing bugs in Ubuntu. When you find a problem, obtain the code, work on a solution, test the fix, push your changes to :term:`Launchpad`, and request a review and merge. .. attention:: diff --git a/docs/contributors/bug-fix/check-if-is-it-already-fixed.md b/docs/contributors/bug-fix/check-if-is-it-already-fixed.md new file mode 100644 index 000000000..2fd166983 --- /dev/null +++ b/docs/contributors/bug-fix/check-if-is-it-already-fixed.md @@ -0,0 +1,255 @@ +(check-if-is-it-already-fixed)= +# Check if it's already been fixed + +Often we can save time by leveraging someone else's work, so it's always +worth doing some research up-front. Fixes for bugs can sometimes be found in +newer versions of Ubuntu, Debian, or upstream, and sometimes in external +forums or bug trackers. + + +### Was it fixed in a newer Ubuntu? + +The easiest way to check is to review the package's status in Ubuntu: + +```none +$ rmadison postfix + postfix | 2.9.1-4 | precise | source, amd64, armel, armhf, i386, powerpc + postfix | 2.9.6-1~12.04.3 | precise-updates | source, amd64, armel, armhf, i386, powerpc + postfix | 2.11.0-1 | trusty | source, amd64, arm64, armhf, i386, powerpc, ppc64el + postfix | 2.11.0-1ubuntu1.2 | trusty-updates | source, amd64, arm64, armhf, i386, powerpc, ppc64el + postfix | 3.1.0-3 | xenial | source, amd64, arm64, armhf, i386, powerpc, ppc64el, s390x + postfix | 3.1.0-3ubuntu0.3 | xenial-updates | source, amd64, arm64, armhf, i386, powerpc, ppc64el, s390x + postfix | 3.3.0-1 | bionic | source, amd64, arm64, armhf, i386, ppc64el, s390x + postfix | 3.3.0-1ubuntu1 | cosmic | source, amd64, arm64, armhf, i386, ppc64el, s390x +``` + +Debian can also be worth checking: + +```none +$ rmadison -u debian postfix +postfix | 3.3.0-1 | testing | source, amd64, arm64, armel, armhf, i386, mips64el, mipsel, ppc64el, s390x +postfix | 3.3.0-1 | unstable | source, amd64, arm64, armel, armhf, i386, mips64el, mipsel, ppc64el, s390x +... +``` + +We see from the first output that `3.3.0-1ubuntu1` exists under Cosmic, so +`postfix` has been modified there. Let's see what was changed. + + +#### Clone the Package + +Find the repository name: + +```none +$ apt-cache show postfix | grep Source: +``` + +In this case, there is no "Source" field, so we just use "`postfix`". + +```none +$ git ubuntu clone postfix postfix-gu +``` + +This will create a new git clone of the postfix repo named `postfix-gu`, with +a remote of `pkg`. The current branch will be `ubuntu-devel`, and the various +versions for each distribution version will be under `pkg/ubuntu/version`. + +Notes: + +* Due to {lpbug}`this bug <1761821>`, you may get: + `fatal: could not read Username for 'https://git.launchpad.net': terminal prompts disabled.` + It's safe to ignore this. + * The first time you run this command, a git-ubuntu entry will be added to + `.gitignore`. + * Sometimes it can be helpful to checkout the git repositories for the + package maintained by Debian and/or upstream. These would be checked out + to "`postfix-debian`" and "`postfix`" respectively. + + +#### View the Commit Log + +```none +$ git log -b pkg/ubuntu/cosmic +... +commit 73cb543efe06a340021cbf538d3ca88abfd96bd8 (tag: pkg/upload/3.3.0-1ubuntu1) +Author: Andreas Hasenack +Date: Wed May 9 10:14:49 2018 -0300 + + changelog + +commit d4cb4562480496f8a1b25ddc397cef45dd45d855 +Author: Andreas Hasenack +Date: Wed May 9 09:51:20 2018 -0300 + + * debian/patches/fix-postconf-segfault.diff: Fix a postconf segfault + when map file cannot be read. Thanks to Viktor Dukhovni . (LP: #1753470) +``` + +`d4cb45` sure looks like a fix for this issue! + +```none +$ git log -b -p pkg/ubuntu/cosmic +... +diff --git a/debian/patches/fix-postconf-segfault.diff b/debian/patches/fix-postconf-segfault.diff +new file mode 100644 +index 00000000..f8eef6bf +--- /dev/null ++++ b/debian/patches/fix-postconf-segfault.diff +@@ -0,0 +1,25 @@ ++Description: Fix a postconf segfault when map file cannot be read ++Author: Viktor Dukhovni ++Origin: https://marc.info/?l=postfix-users&m=152578771531514&w=2 ++Bug-Debian: https://bugs.debian.org/898271 ++Bug-Ubuntu: https://launchpad.net/bugs/1753470 ++Last-Update: 2018-05-09 ++--- ++This patch header follows DEP-3: http://dep.debian.net/deps/dep3/ ++--- a/src/postconf/postconf_dbms.c +++++ b/src/postconf/postconf_dbms.c ++@@ -174,10 +174,10 @@ ++ */ ++ dict = dict_ht_open(dict_spec, O_CREAT | O_RDWR, 0); ++ dict_register(dict_spec, dict); ++- if ((fp = vstream_fopen(cf_file, O_RDONLY, 0)) == 0 ++- && errno != EACCES) { ++- msg_warn("open \"%s\" configuration \"%s\": %m", ++- dp->db_type, cf_file); +++ if ((fp = vstream_fopen(cf_file, O_RDONLY, 0)) == 0) { +++ if (errno != EACCES) +++ msg_warn("open \"%s\" configuration \"%s\": %m", +++ dp->db_type, cf_file); ++ myfree(dict_spec); ++ return; ++ } +diff --git a/debian/patches/series b/debian/patches/series +index c2e47271..1f77ec0b 100644 +--- a/debian/patches/series ++++ b/debian/patches/series +@@ -15,3 +15,4 @@ + 50_LANG.diff + 70_postfix-check.diff + tls_version.diff ++fix-postconf-segfault.diff +``` + +Here we see both the patch and the change to `debian/patches/series` to +include the patch. This is the fix we need! + + +### Was it fixed in Debian? + +Sometimes the fix may have been updated in Debian instead of Ubuntu. There are +many ways to locate fixes from Debian. Debian maintains its own git +repository for many (but not all) of its packages, so having a clone of this +can be handy. + +For example, let's assume for argument's sake that we had a problem with +`sshd` in Xenial, where it would fail to check config files before reloading +([as in this bug](https://bugs.launchpad.net/ubuntu/+source/openssh/+bug/1771340)). +From Debian's `openssh` +[source package page](https://packages.debian.org/source/stretch/openssh), +we find the git repository at `https://salsa.debian.org/ssh-team/openssh` and +can check it out: + +```none +$ git clone https://salsa.debian.org/ssh-team/openssh.git openssh-debian +$ cd openssh-debian +$ git branch -av | cat +* master 296562ba1 releasing package openssh version 1:8.2p1-4 + remotes/origin/HEAD -> origin/master + remotes/origin/buster 6d9ca74c4 releasing package openssh version 1:7.9p1-10+deb10u2 + remotes/origin/etch 851625c74 releasing version 1:4.3p2-9etch1 + remotes/origin/experimental 09a03c340 Update contact information for Natalie Amery + remotes/origin/jessie 9da94db38 Merge branch 'jessie' into 'jessie' + remotes/origin/master 296562ba1 releasing package openssh version 1:8.2p1-4 + remotes/origin/pristine-tar 5fdaf4d7d pristine-tar data for openssh_8.2p1.orig.tar.gz + remotes/origin/sarge f297a6e07 debconf-updatepo + remotes/origin/squeeze faa0b9a59 releasing package openssh version 1:5.5p1-6+squeeze5 + remotes/origin/stretch 0ef21e4e2 Merge branch 'fix-923486-stretch' into 'stretch' + remotes/origin/ubuntu/saucy f8daff632 releasing package openssh version 1:6.2p2-6ubuntu0.5 + remotes/origin/ubuntu/trusty f6ffa5954 releasing package openssh version 1:6.6p1-2ubuntu2 + remotes/origin/ubuntu/xenial bd9cfb441 releasing package openssh version 1:7.2p2-4ubuntu1 + remotes/origin/upstream f0de78bd4 Import openssh_8.2p1.orig.tar.gz + remotes/origin/upstream-experimental 102062f82 Import openssh_8.0p1.orig.tar.gz + remotes/origin/upstream-jessie 487bdb3a5 Import openssh_6.7p1.orig.tar.gz + remotes/origin/upstream-stretch 971a76537 Import openssh_7.4p1.orig.tar.gz + remotes/origin/wheezy e345e2a5f releasing package openssh 1:6.0p1-4+deb7u3 + remotes/origin/wheezy-backports 1d95da812 Remove now-unnecessary backports-specific version changes. +``` + +That's a lot of branches, but the ones of most interest will be `master` and +sometimes `experimental`. `master` is already checked out, so lets peruse its +commit history. Doing this, we find: + +```none +commit d4181e15b03171d1363cd9d7a50b209697a80b01 +Author: Colin Watson +AuthorDate: Mon Jun 26 10:18:26 2017 +0100 +Commit: Colin Watson +CommitDate: Mon Jun 26 10:18:26 2017 +0100 + + Test configuration before starting or reloading sshd under systemd (closes: #865770). +``` + +Our issue would be the same as Debian bug #865770. + +It's also possible to search for commits via Debian's web front-end for git, +[Salsa](https://salsa.debian.org/public). Doing so in this case would bring you to +[this commit](https://salsa.debian.org/ssh-team/openssh/-/commit/d4181e15b03171d1363cd9d7a50b209697a80b01) + +Either way, you should also mention the Salsa link in the fixed-up bug report, +and you should also include it in your fix commit message. + +Since we can't push new versions of packages to previous Ubuntu releases, +you'll need to backport the fix by copying what Debian did into a new commit +on Xenial. + + +### Was it fixed upstream? + +For bugs that aren't already fixed in Ubuntu or Debian, sometimes the original +developers of the software have already found and fixed the issue, or at least +are aware of it and may have a proposed solution or workaround available. + +From the unpacked package directory, a quick way to see if there's a newer +upstream release is via `uscan`: + +```none +$ cd dovecot-gu/ +$ uscan --safe +uscan: Newest version of dovecot on remote site is 2.3.10, local version is 2.3.7.2 +uscan: => Newer package available from + https://dovecot.org/releases/2.3/dovecot-2.3.10.tar.gz +``` + +This only works if the package has a `debian/watches` file. If it doesn't, +look in the package's README or other documentation, and do the research +online manually. + +Searching the upstream bug tracker, or generally Googling error messages or +symptoms can sometimes turn up a patch or bug report of relevance. + + +### Forwarding issues upstream + +If there are no existing fixes for an issue, you can either develop one +yourself, or communicate the problem to Debian or the upstream developers. + +Sometimes clues can be found "in the wild" via random forum posts or bug +trackers, but be aware these can span the full range from high quality to +dangerous - so treat them only as ideas and don't accept anything blindly. + +Each upstream project has its own conventions and expectations for how they +can be communicated with. Check the source tree and the development section of +the upstream project's website for policies, or study other recent bug reports +and patch contributions for best practices to follow. + +In general though, it is a good idea to make sure you are able to reliably +reproduce the issue yourself. Document the steps you took in a way that +non-Ubuntu users could follow. If there is a workload or test case, try to +simplify it down to the minimal set of commands needed to reproduce the issue. + +When filing the bug report or pull request upstream, do identify yourself as +an Ubuntu developer, and your role in forwarding an issue reported against +the distribution. diff --git a/docs/contributors/bug-fix/evalute-the-bug.md b/docs/contributors/bug-fix/evalute-the-bug.md new file mode 100644 index 000000000..41bda81d3 --- /dev/null +++ b/docs/contributors/bug-fix/evalute-the-bug.md @@ -0,0 +1,152 @@ +(evaluate-the-bug)= +## Evaluate the Bug + +Let's look at an example: +[bug #1753470 report](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470). + + +### Bug report description: + +The original bug report was filed with just this description: + +```none +Fresh install of 18.04 server. Every 5 minutes postconf segfaults: + +Mar 5 14:30:05 hostname-here kernel: [ 672.082204] postconf[12975]: segfault at 40 ip 0000564d613ff053 sp 00007ffc39e19b90 error 4 in postconf[564d613e7000+25000] +Mar 5 14:30:06 hostname-here kernel: [ 672.303499] postconf[13004]: segfault at 40 ip 000055b29d0f8053 sp 00007fff72f4b740 error 4 in postconf[55b29d0e0000+25000] +``` + +According to the Apport log (which is automatically attached to the Launchpad +bug by Apport), the crash is caused by following command line: + +```none +$ postconf -h queue_directory +``` + +Running the command in the shell, however, works as expected and lists the +default spool directory (`/var/spool/postfix`). + +```none +ProblemType: Bug +DistroRelease: Ubuntu 18.04 +Package: postfix 3.3.0-1 +ProcVersionSignature: Ubuntu 4.15.0-10.11-generic 4.15.3 +Uname: Linux 4.15.0-10-generic x86_64 +ApportVersion: 2.20.8-0ubuntu10 +Architecture: amd64 +Date: Mon Mar 5 14:26:27 2018 +SourcePackage: postfix +UpgradeStatus: No upgrade log present (probably fresh install) +``` + +Note that the metadata at the end of the description is what gets appended +when the bug report filing is automatically triggered, or if the user uses a +bug reporting assistant (such as Apport). + +Sometimes these types of bug reports will also include an attached +"`something.crash`" file. This is created by the Apport process running on the +user's system at the time of segfault, and typically includes the core dump, +logs, and other relevant information. If the user has provided a `.crash` +file, you can examine the +{ref}`Apport Crash manually ` +to get a useful stacktrace. + + +### Try to reproduce the issue + +Not all bugs can be easily reproduced, and it's not always obvious how to +reproduce even reproducible bugs. In these cases, some bug work will be needed +to isolate the problem ourselves, or you'll need to work with bug reporters to +narrow the cause enough to identify a fix. + +However, in our example case we're lucky. The bug triagers have identified a +way to reproduce the issue, in +[comment #12](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470/comments/12): + +```none +ubuntu@bionic-postfix:~$ postconf virtual_alias_map +Segmentation fault (core dumped) +ubuntu@bionic-postfix:~$ dpkg-query -W postfix +postfix 3.3.0-1 +ubuntu@bionic-postfix:~$ ll /etc/postfix/valiases.cf +-rw-r----- 1 root root 169 May 7 14:08 /etc/postfix/valiases.cf +ubuntu@bionic-postfix:~$ +``` + +Let's see if we can reproduce the issue as well, using these directions. + +Before that, we need to set up an environment for doing the testing. There are +many options for where and how to do your testing, and different developers +have their own preferences. Here's a couple of options: + + +#### Make a test environment + +To make a container for testing: + +```none +$ lxc launch ubuntu-daily:bionic tester +``` + +Alternatively, create a virtual machine (VM) for testing: + +```none +$ lxc launch ubuntu-daily:bionic --vm tester +``` + +With both containers and VMs, you can use the `limits.memory` and `limits.cpu` options to configure available RAM or CPU cores. +For example, to limit the available memory to 2 GiB, and make 2 CPU cores available, add these parameters to the `lxc launch` command: + +```none +-c limits.memory=2GiB -c limits.cpu=2 +``` + +Log into the machine: + +```none +$ lxc exec tester -- sudo -i -u ubuntu +``` + +```{note} +The "ubuntu" user's password is locked, but `sudo` can be run without password. +``` + + +#### Get up to date and install `postfix` + +```none +ubuntu@tester:~$ sudo apt dist-upgrade +ubuntu@tester:~$ sudo apt install -y postfix +``` + + +#### Tell `postfix` to use a map file + +```none +ubuntu@tester:~$ echo "virtual_alias_maps = pgsql:/etc/postfix/valiases.cf" \ + | sudo tee -a /etc/postfix/main.cf +``` + + +#### To reproduce, the file must be unreadable by the current user + +```none +ubuntu@tester:~$ sudo touch /etc/postfix/valiases.cf +ubuntu@tester:~$ sudo chmod 0600 /etc/postfix/valiases.cf +``` + + +#### Reproduce the issue + +```none +ubuntu@tester:~$ /usr/sbin/postconf virtual_alias_map +Segmentation fault (core dumped) +``` + +Now we have confirmed the bug. + +```none + +Keep track of the commands you used to reproduce the bug. You'll need them +later. +``` \ No newline at end of file diff --git a/docs/contributors/bug-fix/fix-a-bug-in-a-package.md b/docs/contributors/bug-fix/fix-a-bug-in-a-package.md deleted file mode 100644 index db28e0f16..000000000 --- a/docs/contributors/bug-fix/fix-a-bug-in-a-package.md +++ /dev/null @@ -1,796 +0,0 @@ -(how-to-fix-a-bug-in-a-package)= -# How to fix a bug in a package - -```{note} -TODO: The following content should be blended together with: - -- {ref}`how-to-propose-changes` -- {ref}`how-to-make-changes-to-a-package` -``` - -In this tutorial we walk through the process of: - -- Evaluating a bug - -- Finding a fix for it - -- Packaging the fix for Ubuntu - -Every bug is unique, of course; this is intended to illustrate the mindset and -steps one should follow generally. - - -## Required reading - -It is strongly recommended that you read the following resources before you -continue, to make sure you are familiar with the concepts: - -* [git-ubuntu-clone](https://ubuntu.com/blog/git-ubuntu-clone) -* [DEP-3](https://dep-team.pages.debian.net/deps/dep3/) -* {ref}`version-strings` -* [Stable Release Updates (SRUs)](https://documentation.ubuntu.com/sru/en/latest/) - - -(evaluate-the-bug)= -## Evaluate the Bug - -Let's look at an example: -[bug #1753470 report](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470). - - -### Bug report description: - -The original bug report was filed with just this description: - -```none -Fresh install of 18.04 server. Every 5 minutes postconf segfaults: - -Mar 5 14:30:05 hostname-here kernel: [ 672.082204] postconf[12975]: segfault at 40 ip 0000564d613ff053 sp 00007ffc39e19b90 error 4 in postconf[564d613e7000+25000] -Mar 5 14:30:06 hostname-here kernel: [ 672.303499] postconf[13004]: segfault at 40 ip 000055b29d0f8053 sp 00007fff72f4b740 error 4 in postconf[55b29d0e0000+25000] -``` - -According to the Apport log (which is automatically attached to the Launchpad -bug by Apport), the crash is caused by following command line: - -```none -$ postconf -h queue_directory -``` - -Running the command in the shell, however, works as expected and lists the -default spool directory (`/var/spool/postfix`). - -```none -ProblemType: Bug -DistroRelease: Ubuntu 18.04 -Package: postfix 3.3.0-1 -ProcVersionSignature: Ubuntu 4.15.0-10.11-generic 4.15.3 -Uname: Linux 4.15.0-10-generic x86_64 -ApportVersion: 2.20.8-0ubuntu10 -Architecture: amd64 -Date: Mon Mar 5 14:26:27 2018 -SourcePackage: postfix -UpgradeStatus: No upgrade log present (probably fresh install) -``` - -Note that the metadata at the end of the description is what gets appended -when the bug report filing is automatically triggered, or if the user uses a -bug reporting assistant (such as Apport). - -Sometimes these types of bug reports will also include an attached -"`something.crash`" file. This is created by the Apport process running on the -user's system at the time of segfault, and typically includes the core dump, -logs, and other relevant information. If the user has provided a `.crash` -file, you can examine the -{ref}`Apport Crash manually ` -to get a useful stacktrace. - - -### Try to reproduce the issue - -Not all bugs can be easily reproduced, and it's not always obvious how to -reproduce even reproducible bugs. In these cases, some bug work will be needed -to isolate the problem ourselves, or you'll need to work with bug reporters to -narrow the cause enough to identify a fix. - -However, in our example case we're lucky. The bug triagers have identified a -way to reproduce the issue, in -[comment #12](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470/comments/12): - -```none -ubuntu@bionic-postfix:~$ postconf virtual_alias_map -Segmentation fault (core dumped) -ubuntu@bionic-postfix:~$ dpkg-query -W postfix -postfix 3.3.0-1 -ubuntu@bionic-postfix:~$ ll /etc/postfix/valiases.cf --rw-r----- 1 root root 169 May 7 14:08 /etc/postfix/valiases.cf -ubuntu@bionic-postfix:~$ -``` - -Let's see if we can reproduce the issue as well, using these directions. - -Before that, we need to set up an environment for doing the testing. There are -many options for where and how to do your testing, and different developers -have their own preferences. Here's a couple of options: - - -#### Make a test environment - -To make a container for testing: - -```none -$ lxc launch ubuntu-daily:bionic tester -``` - -Alternatively, create a virtual machine (VM) for testing: - -```none -$ lxc launch ubuntu-daily:bionic --vm tester -``` - -With both containers and VMs, you can use the `limits.memory` and `limits.cpu` options to configure available RAM or CPU cores. -For example, to limit the available memory to 2 GiB, and make 2 CPU cores available, add these parameters to the `lxc launch` command: - -```none --c limits.memory=2GiB -c limits.cpu=2 -``` - -Log into the machine: - -```none -$ lxc exec tester -- sudo -i -u ubuntu -``` - -```{note} -The "ubuntu" user's password is locked, but `sudo` can be run without password. -``` - - -#### Get up to date and install `postfix` - -```none -ubuntu@tester:~$ sudo apt dist-upgrade -ubuntu@tester:~$ sudo apt install -y postfix -``` - - -#### Tell `postfix` to use a map file - -```none -ubuntu@tester:~$ echo "virtual_alias_maps = pgsql:/etc/postfix/valiases.cf" \ - | sudo tee -a /etc/postfix/main.cf -``` - - -#### To reproduce, the file must be unreadable by the current user - -```none -ubuntu@tester:~$ sudo touch /etc/postfix/valiases.cf -ubuntu@tester:~$ sudo chmod 0600 /etc/postfix/valiases.cf -``` - - -#### Reproduce the issue - -```none -ubuntu@tester:~$ /usr/sbin/postconf virtual_alias_map -Segmentation fault (core dumped) -``` - -Now we have confirmed the bug. - -```none - -Keep track of the commands you used to reproduce the bug. You'll need them -later. -``` - - -## Check if it's already been fixed - -Often we can save time by leveraging someone else's work, so it's always -worth doing some research up-front. Fixes for bugs can sometimes be found in -newer versions of Ubuntu, Debian, or upstream, and sometimes in external -forums or bug trackers. - - -### Was it fixed in a newer Ubuntu? - -The easiest way to check is to review the package's status in Ubuntu: - -```none -$ rmadison postfix - postfix | 2.9.1-4 | precise | source, amd64, armel, armhf, i386, powerpc - postfix | 2.9.6-1~12.04.3 | precise-updates | source, amd64, armel, armhf, i386, powerpc - postfix | 2.11.0-1 | trusty | source, amd64, arm64, armhf, i386, powerpc, ppc64el - postfix | 2.11.0-1ubuntu1.2 | trusty-updates | source, amd64, arm64, armhf, i386, powerpc, ppc64el - postfix | 3.1.0-3 | xenial | source, amd64, arm64, armhf, i386, powerpc, ppc64el, s390x - postfix | 3.1.0-3ubuntu0.3 | xenial-updates | source, amd64, arm64, armhf, i386, powerpc, ppc64el, s390x - postfix | 3.3.0-1 | bionic | source, amd64, arm64, armhf, i386, ppc64el, s390x - postfix | 3.3.0-1ubuntu1 | cosmic | source, amd64, arm64, armhf, i386, ppc64el, s390x -``` - -Debian can also be worth checking: - -```none -$ rmadison -u debian postfix -postfix | 3.3.0-1 | testing | source, amd64, arm64, armel, armhf, i386, mips64el, mipsel, ppc64el, s390x -postfix | 3.3.0-1 | unstable | source, amd64, arm64, armel, armhf, i386, mips64el, mipsel, ppc64el, s390x -... -``` - -We see from the first output that `3.3.0-1ubuntu1` exists under Cosmic, so -`postfix` has been modified there. Let's see what was changed. - - -#### Clone the Package - -Find the repository name: - -```none -$ apt-cache show postfix | grep Source: -``` - -In this case, there is no "Source" field, so we just use "`postfix`". - -```none -$ git ubuntu clone postfix postfix-gu -``` - -This will create a new git clone of the postfix repo named `postfix-gu`, with -a remote of `pkg`. The current branch will be `ubuntu-devel`, and the various -versions for each distribution version will be under `pkg/ubuntu/version`. - -Notes: - -* Due to {lpbug}`this bug <1761821>`, you may get: - `fatal: could not read Username for 'https://git.launchpad.net': terminal prompts disabled.` - It's safe to ignore this. - * The first time you run this command, a git-ubuntu entry will be added to - `.gitignore`. - * Sometimes it can be helpful to checkout the git repositories for the - package maintained by Debian and/or upstream. These would be checked out - to "`postfix-debian`" and "`postfix`" respectively. - - -#### View the Commit Log - -```none -$ git log -b pkg/ubuntu/cosmic -... -commit 73cb543efe06a340021cbf538d3ca88abfd96bd8 (tag: pkg/upload/3.3.0-1ubuntu1) -Author: Andreas Hasenack -Date: Wed May 9 10:14:49 2018 -0300 - - changelog - -commit d4cb4562480496f8a1b25ddc397cef45dd45d855 -Author: Andreas Hasenack -Date: Wed May 9 09:51:20 2018 -0300 - - * debian/patches/fix-postconf-segfault.diff: Fix a postconf segfault - when map file cannot be read. Thanks to Viktor Dukhovni . (LP: #1753470) -``` - -`d4cb45` sure looks like a fix for this issue! - -```none -$ git log -b -p pkg/ubuntu/cosmic -... -diff --git a/debian/patches/fix-postconf-segfault.diff b/debian/patches/fix-postconf-segfault.diff -new file mode 100644 -index 00000000..f8eef6bf ---- /dev/null -+++ b/debian/patches/fix-postconf-segfault.diff -@@ -0,0 +1,25 @@ -+Description: Fix a postconf segfault when map file cannot be read -+Author: Viktor Dukhovni -+Origin: https://marc.info/?l=postfix-users&m=152578771531514&w=2 -+Bug-Debian: https://bugs.debian.org/898271 -+Bug-Ubuntu: https://launchpad.net/bugs/1753470 -+Last-Update: 2018-05-09 -+--- -+This patch header follows DEP-3: http://dep.debian.net/deps/dep3/ -+--- a/src/postconf/postconf_dbms.c -++++ b/src/postconf/postconf_dbms.c -+@@ -174,10 +174,10 @@ -+ */ -+ dict = dict_ht_open(dict_spec, O_CREAT | O_RDWR, 0); -+ dict_register(dict_spec, dict); -+- if ((fp = vstream_fopen(cf_file, O_RDONLY, 0)) == 0 -+- && errno != EACCES) { -+- msg_warn("open \"%s\" configuration \"%s\": %m", -+- dp->db_type, cf_file); -++ if ((fp = vstream_fopen(cf_file, O_RDONLY, 0)) == 0) { -++ if (errno != EACCES) -++ msg_warn("open \"%s\" configuration \"%s\": %m", -++ dp->db_type, cf_file); -+ myfree(dict_spec); -+ return; -+ } -diff --git a/debian/patches/series b/debian/patches/series -index c2e47271..1f77ec0b 100644 ---- a/debian/patches/series -+++ b/debian/patches/series -@@ -15,3 +15,4 @@ - 50_LANG.diff - 70_postfix-check.diff - tls_version.diff -+fix-postconf-segfault.diff -``` - -Here we see both the patch and the change to `debian/patches/series` to -include the patch. This is the fix we need! - - -### Was it fixed in Debian? - -Sometimes the fix may have been updated in Debian instead of Ubuntu. There are -many ways to locate fixes from Debian. Debian maintains its own git -repository for many (but not all) of its packages, so having a clone of this -can be handy. - -For example, let's assume for argument's sake that we had a problem with -`sshd` in Xenial, where it would fail to check config files before reloading -([as in this bug](https://bugs.launchpad.net/ubuntu/+source/openssh/+bug/1771340)). -From Debian's `openssh` -[source package page](https://packages.debian.org/source/stretch/openssh), -we find the git repository at `https://salsa.debian.org/ssh-team/openssh` and -can check it out: - -```none -$ git clone https://salsa.debian.org/ssh-team/openssh.git openssh-debian -$ cd openssh-debian -$ git branch -av | cat -* master 296562ba1 releasing package openssh version 1:8.2p1-4 - remotes/origin/HEAD -> origin/master - remotes/origin/buster 6d9ca74c4 releasing package openssh version 1:7.9p1-10+deb10u2 - remotes/origin/etch 851625c74 releasing version 1:4.3p2-9etch1 - remotes/origin/experimental 09a03c340 Update contact information for Natalie Amery - remotes/origin/jessie 9da94db38 Merge branch 'jessie' into 'jessie' - remotes/origin/master 296562ba1 releasing package openssh version 1:8.2p1-4 - remotes/origin/pristine-tar 5fdaf4d7d pristine-tar data for openssh_8.2p1.orig.tar.gz - remotes/origin/sarge f297a6e07 debconf-updatepo - remotes/origin/squeeze faa0b9a59 releasing package openssh version 1:5.5p1-6+squeeze5 - remotes/origin/stretch 0ef21e4e2 Merge branch 'fix-923486-stretch' into 'stretch' - remotes/origin/ubuntu/saucy f8daff632 releasing package openssh version 1:6.2p2-6ubuntu0.5 - remotes/origin/ubuntu/trusty f6ffa5954 releasing package openssh version 1:6.6p1-2ubuntu2 - remotes/origin/ubuntu/xenial bd9cfb441 releasing package openssh version 1:7.2p2-4ubuntu1 - remotes/origin/upstream f0de78bd4 Import openssh_8.2p1.orig.tar.gz - remotes/origin/upstream-experimental 102062f82 Import openssh_8.0p1.orig.tar.gz - remotes/origin/upstream-jessie 487bdb3a5 Import openssh_6.7p1.orig.tar.gz - remotes/origin/upstream-stretch 971a76537 Import openssh_7.4p1.orig.tar.gz - remotes/origin/wheezy e345e2a5f releasing package openssh 1:6.0p1-4+deb7u3 - remotes/origin/wheezy-backports 1d95da812 Remove now-unnecessary backports-specific version changes. -``` - -That's a lot of branches, but the ones of most interest will be `master` and -sometimes `experimental`. `master` is already checked out, so lets peruse its -commit history. Doing this, we find: - -```none -commit d4181e15b03171d1363cd9d7a50b209697a80b01 -Author: Colin Watson -AuthorDate: Mon Jun 26 10:18:26 2017 +0100 -Commit: Colin Watson -CommitDate: Mon Jun 26 10:18:26 2017 +0100 - - Test configuration before starting or reloading sshd under systemd (closes: #865770). -``` - -Our issue would be the same as Debian bug #865770. - -It's also possible to search for commits via Debian's web front-end for git, -[Salsa](https://salsa.debian.org/public). Doing so in this case would bring you to -[this commit](https://salsa.debian.org/ssh-team/openssh/-/commit/d4181e15b03171d1363cd9d7a50b209697a80b01) - -Either way, you should also mention the Salsa link in the fixed-up bug report, -and you should also include it in your fix commit message. - -Since we can't push new versions of packages to previous Ubuntu releases, -you'll need to backport the fix by copying what Debian did into a new commit -on Xenial. - - -### Was it fixed upstream? - -For bugs that aren't already fixed in Ubuntu or Debian, sometimes the original -developers of the software have already found and fixed the issue, or at least -are aware of it and may have a proposed solution or workaround available. - -From the unpacked package directory, a quick way to see if there's a newer -upstream release is via `uscan`: - -```none -$ cd dovecot-gu/ -$ uscan --safe -uscan: Newest version of dovecot on remote site is 2.3.10, local version is 2.3.7.2 -uscan: => Newer package available from - https://dovecot.org/releases/2.3/dovecot-2.3.10.tar.gz -``` - -This only works if the package has a `debian/watches` file. If it doesn't, -look in the package's README or other documentation, and do the research -online manually. - -Searching the upstream bug tracker, or generally Googling error messages or -symptoms can sometimes turn up a patch or bug report of relevance. - - -### Forwarding issues upstream - -If there are no existing fixes for an issue, you can either develop one -yourself, or communicate the problem to Debian or the upstream developers. - -Sometimes clues can be found "in the wild" via random forum posts or bug -trackers, but be aware these can span the full range from high quality to -dangerous - so treat them only as ideas and don't accept anything blindly. - -Each upstream project has its own conventions and expectations for how they -can be communicated with. Check the source tree and the development section of -the upstream project's website for policies, or study other recent bug reports -and patch contributions for best practices to follow. - -In general though, it is a good idea to make sure you are able to reliably -reproduce the issue yourself. Document the steps you took in a way that -non-Ubuntu users could follow. If there is a workload or test case, try to -simplify it down to the minimal set of commands needed to reproduce the issue. - -When filing the bug report or pull request upstream, do identify yourself as -an Ubuntu developer, and your role in forwarding an issue reported against -the distribution. - - -## Apply the fix - -Changes to packages are done via patches. -- `debian/patches/` stores the patches themselves, under the root of the - package repository. -- `debian/patches/series` lists the order in which the patches should be - applied. -- `debian/changelog` lists the changes made to the package over time. - -We use `git-ubuntu` to make changes to packages. - - -### Step 1: Assign the task to yourself - -First, going back to our [example case](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470) - -Go to the task (row) that starts with "bionic" and assign the task to yourself. - -Switch the status to "in progress" using the yellow pencil icons. - - -### Step 2: Clone the package (if you haven't already) - -Find the repository name: - -```none -$ apt-cache show postfix | grep Source: -``` - -In this case, there is no Source field, so we just use `postfix`. - -```none -$ git ubuntu clone postfix postfix-gu -$ cd postfix-gu -``` - - -### Step 3: Make a branch based on the appropriate Ubuntu branch - -The affected version of `postfix` is in Bionic, so we branch from -`bionic-devel`. It helps to use a descriptive branch name. - -```none -$ git checkout pkg/ubuntu/bionic-devel -b postfix-sru-lp1753470-segfault-bionic -``` - - -### Step 4: Make a patch to fix the issue (maybe) - -If the only changes you made are within the `debian/` sub-directory, you don't -need a patchfile, and can skip this step. - -On the other hand, if you've made changes to the upstream code (anything -outside of the `debian/` directory), you'll need to generate a patch in -`debian/patches`. - -For instructions, see {ref}`how-to-work-with-debian-patches`. - - -### Step 5: Commit the patch - -See {ref}`how-to-commit-changes`. - - -## Build a fixed package - -See {ref}`how-to-build-packages-in-a-ppa`. - - -## Test the Package - - -### Start a Bionic container and enter it: - -We can name our LXC containers with any scheme we wish, such as 'tester' -earlier for a temporary one to test with. However, for bug fixes we'll often -need to keep the container around for reference as the bug fix goes through -the review, sponsorship, and SRU processes. - -So, to keep things consistent let's reuse our git branch name, and just -prefix the package name: - -```none -$ lxc launch ubuntu:bionic postfix-sru-lp1753470-segfault-bionic -Creating postfix-sru-lp1753470-segfault-bionic -Starting postfix-sru-lp1753470-segfault-bionic - -$ lxc exec postfix-sru-lp1753470-segfault-bionic -- bash -root@postfix-sru-lp1753470-segfault-bionic:~# -``` - - -### Reproduce the bug - -Record your steps as you go (you'll need them later): - -```none -# apt dist-upgrade -# apt install -y postfix -# touch /etc/postfix/valiases.cf -# chmod 0600 /etc/postfix/valiases.cf -# echo "virtual_alias_maps = pgsql:/etc/postfix/valiases.cf" >> /etc/postfix/main.cf -# su - ubuntu -$ /usr/sbin/postconf virtual_alias_map -Segmentation fault (core dumped) -``` - - -### Install the fixed package - -In this case, I'm using a PPA. Alternatively, if you've built locally, you can -copy in the `.deb` file and install it manually. - -```none -$ sudo add-apt-repository -ys ppa:kstenerud/postfix-sru-lp1753470-segfault -$ sudo apt update -$ sudo apt upgrade -y -``` - - -### Test the bug again - -```none -$ /usr/sbin/postconf virtual_alias_map -/usr/sbin/postconf: warning: virtual_alias_map: unknown parameter -``` - -The bug is fixed! Sweet! - - -## Run the package tests - -The DEP-8 autopkgtests don't exercise our bug, but are worth running as -just-in-case checks (and to catch regressions). See {ref}`how-to-run-package-tests`. - -Any change in behavior should be considered as priorities to resolve before -proceeding. - - -## Start a merge proposal - -See {ref}`how-to-submit-a-merge-proposal`. - - -## Update the bug report - -For regular bug fixes and merges, adding a comment about your progress is -typically all you'll need. You might provide some links to your PPA if you'd -like to get people to test your fix, or if you want to provide the fix to the -user-base swiftly. - - -### SRU paperwork - -For stable release updates (SRUs), on the other hand, you need to add a bit -more detail. - -Go back to the -[example bug report](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470). - -Modify the bug description (yellow pencil icon) and update it to conform with -[the SRU bug template](https://documentation.ubuntu.com/sru/en/latest/reference/bug-template/). -These are normally the "Impact", "Test Case" and "Where problems could occur" -sections. - -It is good practice to make the "Test Case" section itemized with explicit -steps, "paint-by-numbers" style. It is also best practice to include both a -"Development Fix" and "Stable Fix"; the former explains the situation with the -fix in the current development release, while the latter explains your -strategy for addressing (or skipping) it in LTS and other stable releases. - -```{note} - -Keep the original description as-is, in a section called -"Original Description" at the bottom. -``` - -```{note} -You'll see your branch and merge proposal in the `Related branches` because of -the (`LP: #NNNNNN`) in the changelog entry. -``` - - -### SRU exceptions - -There is a particular kind of -[special case SRU](https://documentation.ubuntu.com/sru/en/latest/reference/package-specific/) -which is called either a Minor Release Exception (MRE) or an SRU exception. In -the former we assume upstream is so stable and similar to our needs, process -and philosophy that fewer checks need to be done, in the latter we admit that -there is more to check - but both do more than the isolated individual bug -fixing that a normal SRU would do. - -The work to get these exceptions granted gives us confidence that the minor -releases created by upstream take sufficient care over testing, ABI & API -stability, smooth upgradability, and other things important for an SRU. - -Each case is slightly different, which is why each of them gets their own -discussion and their own accepted process listed in -[SRU special cases](https://documentation.ubuntu.com/sru/en/latest/reference/package-specific/) -of how that particular minor release will be served. - -When we (in the server team) prepare special SRU updates they follow all the -normal SRU rules as outlined here, but in addition will follow all steps and -requirements outlined in the particular SRU exception. That usually includes -additional checks and validations. - -There is one more thing that we (the server team) can do in addition for any -SRU exception upload that we work on. That is, to double check upstream -release notes and changelogs to ensure that there was really nothing that -would unexpectedly break the "stable" in SRU. - -That is worthwhile for MREs where we expect nothing should(TM) -happen and even more so for general SRU exceptions. - -After having passed an SRU exception process, there is always a small chance -that the upstream project might have a slightly different stance/decision -policy with regard to stable releases. This check by our team will help to -serve those updates in the stable and reliable fashion our users expect them -to be. - -To be clear, the expectation is that we should not find anything in this -check, but this is a classic case of "better safe than sorry". - - -## SRU review process - -There is a distinction between sponsorship and the SRU process. They are -possibly a little confused in the SRU wiki page (especially section 6 “Fixing -several bugs in one upload"). - -Consider the process from the point of view of your sponsor and the SRU team. -On review, they will start from the diff and expect to see: - -* **The diff fully explained by the changelog entry**. - This means that if there is something in the diff that isn't explained by - the changelog, then there is a problem. -* **A bug for everything mentioned in the changelog entry**. - Reviewers are pragmatic: there is no strict rule that "every bullet point - must refer to a bug", but rather that logically everything mentioned should - correspond to a bug so the reviewer can go to a bug to find more info on - any part of the changelog. - - For an SRU, even added functionality must refer to a bug. If some part of a - changelog entry does not obviously refer to a bug, then there is a problem. -* **Every issue mentioned in an SRU changelog must have a bug task filed - against the package**. The same bug # can be mentioned in different SRUs, - since a bug may have multiple bug tasks. The Ubuntu Bug Control Team, or - other members of the server team can assist if you need help creating bug - tasks. -* **The issue should be resolved for the Ubuntu development release**. This is - tracked by having a bug task set to "Fix Released" for the devel series. - The goal is to avoid regression from a user’s perspective when they upgrade - to the newer Ubuntu release. If the status is not "Fix Released" but you - still want to proceed with the SRU, explain what is going on in a - "Development Fix" section. -* **Every LP bug # mentioned in an SRU changelog must have "SRU paperwork" - filled out**. As described in the previous section. - -After you or your sponsor have uploaded your package: -* Set the bug task status to "In Progress". -* The upload will appear in the "unapproved queue", for example - `https://launchpad.net/ubuntu/focal/+queue?queue_state=1`. It may take a - week or two before it gets processed. -* If you find a problem while it's still unapproved, ask in the Libera Chat - `#ubuntu-release` channel for the package to be rejected from the queue. - This is a trivial task for archive admins. If rejected at this stage, then - the same version number can be re-used in a subsequent upload. -* The SRU team will review incoming SRU uploads from the unapproved queue and - expect to see the review items completed correctly as above. They will - either accept or reject (with a reason) from the unapproved queue. If they - reject, then you will need to handle the rejection reason and then start - again from the beginning. If they accept, then the bug task will change to - "Fix Committed", the package will enter the `-proposed` pocket and then the - package binaries will be built. - - -## When the bugfix is accepted - - -### The acceptance email - -You'll receive an email notification that the bugfix was accepted: - -```none -Accepted postfix into bionic-proposed. The package will build now and be -available at -https://launchpad.net/ubuntu/+source/postfix/3.3.0-1ubuntu0.1 in a few -hours, and then in the -proposed repository. - -Please help us by testing this new package. See -https://wiki.ubuntu.com/Testing/EnableProposed for documentation on how -to enable and use -proposed.Your feedback will aid us getting this -update out to other Ubuntu users. - -If this package fixes the bug for you, please add a comment to this bug, -mentioning the version of the package you tested and change the tag from -verification-needed-bionic to verification-done-bionic. If it does not -fix the bug for you, please add a comment stating that, and change the -tag to verification-failed-bionic. In either case, details of your -testing will help us make a better decision. - -Further information regarding the verification process can be found at -https://wiki.ubuntu.com/QATeam/PerformingSRUVerification . Thank you in -advance! - -** Changed in: postfix (Ubuntu Bionic) - Status: In Progress => Fix Committed - -** Tags added: verification-needed verification-needed-bionic -``` - -Follow the -[build link](https://launchpad.net/ubuntu/+source/postfix/3.3.0-1ubuntu0.1) -and make sure it's publishing to the correct place (Bionic), and that the -builds completed (green check marks). - - -### The excuses page - -Check the "excuses" or "migration" page, -[for Bionic](https://ubuntu-archive-team.ubuntu.com/proposed-migration/bionic/update_excuses.html) -in this case. - -[General page](https://ubuntu-archive-team.ubuntu.com/proposed-migration/update_excuses.html) - -Eventually, the package with your fixes will appear there (search for -`postfix` in this case). It will show the DEP-8 tests for `postfix` and -anything that depends on it. Any tests that fail will show in red. - -```{note} -This page is generated every few minutes, and doesn't update in real-time. -``` - - -### SRU verification - -It's best to have the package independently verified (preferably by the person -who reported the bug), but if it sits idle too long (2 days or so), you can -verify it yourself. Follow the -[instructions provided](https://documentation.ubuntu.com/sru/en/latest/howto/common-issues/) -by the SRU team, which usually means changing the "verification-needed" tag -into "verification-done". - -[Pending SRU](https://ubuntu-archive-team.ubuntu.com/pending-sru.html) shows which SRUs -are pending and what their status is. Note that this includes DEP-8 test -results; if these have failed then it's unlikely the SRU team will release -the update, so it's wise to follow-up if this happens. - -Once all of the SRU's bugs have reached `verification-done` and a 7-day -waiting period has elapsed, the SRU team will move the source and binary -packages into the `-updates` pocket and mark the bug task(s) as "Fix Released". - diff --git a/docs/contributors/bug-fix/index.md b/docs/contributors/bug-fix/index.md index fb58b3517..1cd1e6ff3 100644 --- a/docs/contributors/bug-fix/index.md +++ b/docs/contributors/bug-fix/index.md @@ -1,20 +1,36 @@ (fixing-bugs)= # Fixing bugs +The process of bug fixing in Ubuntu consists of: -## Fixing bugs in packages +- Evaluating a bug + +- Finding a fix for it + +- Packaging the fix for Ubuntu + +Every bug is unique, of course; this is intended to illustrate the mindset and +steps one should follow generally. + +## Bugfixing workflow ```{toctree} :maxdepth: 1 +Bugfixing workflow +``` +## Bugfixing steps -Get a new upstream version -Extract packages -Install built packages -Fix a bug in a package -Build packages in a PPA -Build packages locally -Propose changes -Run package tests +```{toctree} +:maxdepth: 1 +Evaluate the bug +Check if it's already been fixed +Apply the fix +Build a fixed package +Validate the fix +Run the package tests +Submit a merge proposal +Update the bug report +Once the fix is accepted ``` ## Checklists diff --git a/docs/contributors/bug-fix/once-the-fix-is-accepted.md b/docs/contributors/bug-fix/once-the-fix-is-accepted.md new file mode 100644 index 000000000..ed24204a4 --- /dev/null +++ b/docs/contributors/bug-fix/once-the-fix-is-accepted.md @@ -0,0 +1,77 @@ +(once-the-bugfix-is-accepted)= +## Once the bugfix is accepted + + +### The acceptance email + +You'll receive an email notification that the bugfix was accepted: + +```none +Accepted postfix into bionic-proposed. The package will build now and be +available at +https://launchpad.net/ubuntu/+source/postfix/3.3.0-1ubuntu0.1 in a few +hours, and then in the -proposed repository. + +Please help us by testing this new package. See +https://wiki.ubuntu.com/Testing/EnableProposed for documentation on how +to enable and use -proposed.Your feedback will aid us getting this +update out to other Ubuntu users. + +If this package fixes the bug for you, please add a comment to this bug, +mentioning the version of the package you tested and change the tag from +verification-needed-bionic to verification-done-bionic. If it does not +fix the bug for you, please add a comment stating that, and change the +tag to verification-failed-bionic. In either case, details of your +testing will help us make a better decision. + +Further information regarding the verification process can be found at +https://wiki.ubuntu.com/QATeam/PerformingSRUVerification . Thank you in +advance! + +** Changed in: postfix (Ubuntu Bionic) + Status: In Progress => Fix Committed + +** Tags added: verification-needed verification-needed-bionic +``` + +Follow the +[build link](https://launchpad.net/ubuntu/+source/postfix/3.3.0-1ubuntu0.1) +and make sure it's publishing to the correct place (Bionic), and that the +builds completed (green check marks). + + +### The excuses page + +Check the "excuses" or "migration" page, +[for Bionic](https://ubuntu-archive-team.ubuntu.com/proposed-migration/bionic/update_excuses.html) +in this case. + +[General page](https://ubuntu-archive-team.ubuntu.com/proposed-migration/update_excuses.html) + +Eventually, the package with your fixes will appear there (search for +`postfix` in this case). It will show the DEP-8 tests for `postfix` and +anything that depends on it. Any tests that fail will show in red. + +```{note} +This page is generated every few minutes, and doesn't update in real-time. +``` + + +### SRU verification + +It's best to have the package independently verified (preferably by the person +who reported the bug), but if it sits idle too long (2 days or so), you can +verify it yourself. Follow the +[instructions provided](https://documentation.ubuntu.com/sru/en/latest/howto/common-issues/) +by the SRU team, which usually means changing the "verification-needed" tag +into "verification-done". + +[Pending SRU](https://ubuntu-archive-team.ubuntu.com/pending-sru.html) shows which SRUs +are pending and what their status is. Note that this includes DEP-8 test +results; if these have failed then it's unlikely the SRU team will release +the update, so it's wise to follow-up if this happens. + +Once all of the SRU's bugs have reached `verification-done` and a 7-day +waiting period has elapsed, the SRU team will move the source and binary +packages into the `-updates` pocket and mark the bug task(s) as "Fix Released". + diff --git a/docs/contributors/bug-fix/update-the-bug-report.md b/docs/contributors/bug-fix/update-the-bug-report.md new file mode 100644 index 000000000..d2ac477d9 --- /dev/null +++ b/docs/contributors/bug-fix/update-the-bug-report.md @@ -0,0 +1,132 @@ +(update-the-bug-report)= +## Update the bug report + +For regular bug fixes and merges, adding a comment about your progress is +typically all you'll need. You might provide some links to your PPA if you'd +like to get people to test your fix, or if you want to provide the fix to the +user-base swiftly. + + +### SRU paperwork + +For stable release updates (SRUs), on the other hand, you need to add a bit +more detail. + +Go back to the +[example bug report](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470). + +Modify the bug description (yellow pencil icon) and update it to conform with +[the SRU bug template](https://documentation.ubuntu.com/sru/en/latest/reference/bug-template/). +These are normally the "Impact", "Test Case" and "Where problems could occur" +sections. + +It is good practice to make the "Test Case" section itemized with explicit +steps, "paint-by-numbers" style. It is also best practice to include both a +"Development Fix" and "Stable Fix"; the former explains the situation with the +fix in the current development release, while the latter explains your +strategy for addressing (or skipping) it in LTS and other stable releases. + +```{note} + +Keep the original description as-is, in a section called +"Original Description" at the bottom. +``` + +```{note} +You'll see your branch and merge proposal in the `Related branches` because of +the (`LP: #NNNNNN`) in the changelog entry. +``` + + +### SRU exceptions + +There is a particular kind of +[special case SRU](https://documentation.ubuntu.com/sru/en/latest/reference/package-specific/) +which is called either a Minor Release Exception (MRE) or an SRU exception. In +the former we assume upstream is so stable and similar to our needs, process +and philosophy that fewer checks need to be done, in the latter we admit that +there is more to check - but both do more than the isolated individual bug +fixing that a normal SRU would do. + +The work to get these exceptions granted gives us confidence that the minor +releases created by upstream take sufficient care over testing, ABI & API +stability, smooth upgradability, and other things important for an SRU. + +Each case is slightly different, which is why each of them gets their own +discussion and their own accepted process listed in +[SRU special cases](https://documentation.ubuntu.com/sru/en/latest/reference/package-specific/) +of how that particular minor release will be served. + +When we (in the server team) prepare special SRU updates they follow all the +normal SRU rules as outlined here, but in addition will follow all steps and +requirements outlined in the particular SRU exception. That usually includes +additional checks and validations. + +There is one more thing that we (the server team) can do in addition for any +SRU exception upload that we work on. That is, to double check upstream +release notes and changelogs to ensure that there was really nothing that +would unexpectedly break the "stable" in SRU. + +That is worthwhile for MREs where we expect nothing should(TM) +happen and even more so for general SRU exceptions. + +After having passed an SRU exception process, there is always a small chance +that the upstream project might have a slightly different stance/decision +policy with regard to stable releases. This check by our team will help to +serve those updates in the stable and reliable fashion our users expect them +to be. + +To be clear, the expectation is that we should not find anything in this +check, but this is a classic case of "better safe than sorry". + + +## SRU review process + +There is a distinction between sponsorship and the SRU process. They are +possibly a little confused in the SRU wiki page (especially section 6 “Fixing +several bugs in one upload"). + +Consider the process from the point of view of your sponsor and the SRU team. +On review, they will start from the diff and expect to see: + +* **The diff fully explained by the changelog entry**. + This means that if there is something in the diff that isn't explained by + the changelog, then there is a problem. +* **A bug for everything mentioned in the changelog entry**. + Reviewers are pragmatic: there is no strict rule that "every bullet point + must refer to a bug", but rather that logically everything mentioned should + correspond to a bug so the reviewer can go to a bug to find more info on + any part of the changelog. + + For an SRU, even added functionality must refer to a bug. If some part of a + changelog entry does not obviously refer to a bug, then there is a problem. +* **Every issue mentioned in an SRU changelog must have a bug task filed + against the package**. The same bug # can be mentioned in different SRUs, + since a bug may have multiple bug tasks. The Ubuntu Bug Control Team, or + other members of the server team can assist if you need help creating bug + tasks. +* **The issue should be resolved for the Ubuntu development release**. This is + tracked by having a bug task set to "Fix Released" for the devel series. + The goal is to avoid regression from a user’s perspective when they upgrade + to the newer Ubuntu release. If the status is not "Fix Released" but you + still want to proceed with the SRU, explain what is going on in a + "Development Fix" section. +* **Every LP bug # mentioned in an SRU changelog must have "SRU paperwork" + filled out**. As described in the previous section. + +After you or your sponsor have uploaded your package: +* Set the bug task status to "In Progress". +* The upload will appear in the "unapproved queue", for example + `https://launchpad.net/ubuntu/focal/+queue?queue_state=1`. It may take a + week or two before it gets processed. +* If you find a problem while it's still unapproved, ask in the Libera Chat + `#ubuntu-release` channel for the package to be rejected from the queue. + This is a trivial task for archive admins. If rejected at this stage, then + the same version number can be re-used in a subsequent upload. +* The SRU team will review incoming SRU uploads from the unapproved queue and + expect to see the review items completed correctly as above. They will + either accept or reject (with a reason) from the unapproved queue. If they + reject, then you will need to handle the rejection reason and then start + again from the beginning. If they accept, then the bug task will change to + "Fix Committed", the package will enter the `-proposed` pocket and then the + package binaries will be built. diff --git a/docs/contributors/bug-fix/validate-the-fix.md b/docs/contributors/bug-fix/validate-the-fix.md new file mode 100644 index 000000000..646caad31 --- /dev/null +++ b/docs/contributors/bug-fix/validate-the-fix.md @@ -0,0 +1,60 @@ +(validate-the-fix)= +## Validate the fix + + +### Start a Bionic container and enter it: + +We can name our LXC containers with any scheme we wish, such as 'tester' +earlier for a temporary one to test with. However, for bug fixes we'll often +need to keep the container around for reference as the bug fix goes through +the review, sponsorship, and SRU processes. + +So, to keep things consistent let's reuse our git branch name, and just +prefix the package name: + +```none +$ lxc launch ubuntu:bionic postfix-sru-lp1753470-segfault-bionic +Creating postfix-sru-lp1753470-segfault-bionic +Starting postfix-sru-lp1753470-segfault-bionic + +$ lxc exec postfix-sru-lp1753470-segfault-bionic -- bash +root@postfix-sru-lp1753470-segfault-bionic:~# +``` + + +### Reproduce the bug + +Record your steps as you go (you'll need them later): + +```none +# apt dist-upgrade +# apt install -y postfix +# touch /etc/postfix/valiases.cf +# chmod 0600 /etc/postfix/valiases.cf +# echo "virtual_alias_maps = pgsql:/etc/postfix/valiases.cf" >> /etc/postfix/main.cf +# su - ubuntu +$ /usr/sbin/postconf virtual_alias_map +Segmentation fault (core dumped) +``` + + +### Install the fixed package + +In this case, I'm using a PPA. Alternatively, if you've built locally, you can +copy in the `.deb` file and install it manually. + +```none +$ sudo add-apt-repository -ys ppa:kstenerud/postfix-sru-lp1753470-segfault +$ sudo apt update +$ sudo apt upgrade -y +``` + + +### Test the bug again + +```none +$ /usr/sbin/postconf virtual_alias_map +/usr/sbin/postconf: warning: virtual_alias_map: unknown parameter +``` + +The bug is fixed! Sweet! diff --git a/docs/contributors/building/index.md b/docs/contributors/building/index.md index 5c8fc0bec..e77717fb0 100644 --- a/docs/contributors/building/index.md +++ b/docs/contributors/building/index.md @@ -1,6 +1,9 @@ (building)= # Building +The package can be built either locally or in a Launchpad PPA. It is always recommended to test that the package installs and passes its tests +before submitting a merge proposal. + ```{toctree} :maxdepth: 1 From da69798037d6cecd3cf1b93f9e1daa38118a3612 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Wed, 25 Mar 2026 19:16:09 +1300 Subject: [PATCH 13/18] fix: update headings --- docs/contributors/bug-fix/apply-the-fix.md | 12 ++++++------ .../bug-fix/check-if-is-it-already-fixed.md | 12 ++++++------ docs/contributors/bug-fix/evalute-the-bug.md | 14 +++++++------- .../bug-fix/once-the-fix-is-accepted.md | 8 ++++---- docs/contributors/bug-fix/update-the-bug-report.md | 6 +++--- 5 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/contributors/bug-fix/apply-the-fix.md b/docs/contributors/bug-fix/apply-the-fix.md index aad8f87a6..e1959f056 100644 --- a/docs/contributors/bug-fix/apply-the-fix.md +++ b/docs/contributors/bug-fix/apply-the-fix.md @@ -1,4 +1,4 @@ -## Apply the fix +# Apply the fix Whether the bug fix originates from an upstream project or your own work, changes must be managed via patches: @@ -8,7 +8,7 @@ changes must be managed via patches: In our workflow, we use `git-ubuntu` to manage and apply these changes to packages. -### Step 1: Assign the task to yourself +## Step 1: Assign the task to yourself First, going back to our [example case](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470) @@ -17,7 +17,7 @@ Go to the task (row) that starts with "bionic" and assign the task to yourself. Switch the status to "in progress" using the yellow pencil icons. -### Step 2: Clone the package (if you haven't already) +## Step 2: Clone the package (if you haven't already) Find the repository name: @@ -33,7 +33,7 @@ $ cd postfix-gu ``` -### Step 3: Make a branch based on the appropriate Ubuntu branch +## Step 3: Make a branch based on the appropriate Ubuntu branch The affected version of `postfix` is in Bionic, so we branch from `bionic-devel`. It helps to use a descriptive branch name. @@ -43,7 +43,7 @@ $ git checkout pkg/ubuntu/bionic-devel -b postfix-sru-lp1753470-segfault-bionic ``` -### Step 4: Make a patch to fix the issue (maybe) +## Step 4: Make a patch to fix the issue (maybe) If the only changes you made are within the `debian/` sub-directory, you don't need a patchfile, and can skip this step. @@ -55,6 +55,6 @@ outside of the `debian/` directory), you'll need to generate a patch in For instructions, see {ref}`how-to-work-with-debian-patches`. -### Step 5: Commit the patch +## Step 5: Commit the patch See {ref}`how-to-commit-changes`. diff --git a/docs/contributors/bug-fix/check-if-is-it-already-fixed.md b/docs/contributors/bug-fix/check-if-is-it-already-fixed.md index 2fd166983..38410c3c8 100644 --- a/docs/contributors/bug-fix/check-if-is-it-already-fixed.md +++ b/docs/contributors/bug-fix/check-if-is-it-already-fixed.md @@ -7,7 +7,7 @@ newer versions of Ubuntu, Debian, or upstream, and sometimes in external forums or bug trackers. -### Was it fixed in a newer Ubuntu? +## Was it fixed in a newer Ubuntu? The easiest way to check is to review the package's status in Ubuntu: @@ -36,7 +36,7 @@ We see from the first output that `3.3.0-1ubuntu1` exists under Cosmic, so `postfix` has been modified there. Let's see what was changed. -#### Clone the Package +### Clone the Package Find the repository name: @@ -66,7 +66,7 @@ Notes: to "`postfix-debian`" and "`postfix`" respectively. -#### View the Commit Log +### View the Commit Log ```none $ git log -b pkg/ubuntu/cosmic @@ -137,7 +137,7 @@ Here we see both the patch and the change to `debian/patches/series` to include the patch. This is the fix we need! -### Was it fixed in Debian? +## Was it fixed in Debian? Sometimes the fix may have been updated in Debian instead of Ubuntu. There are many ways to locate fixes from Debian. Debian maintains its own git @@ -206,7 +206,7 @@ you'll need to backport the fix by copying what Debian did into a new commit on Xenial. -### Was it fixed upstream? +## Was it fixed upstream? For bugs that aren't already fixed in Ubuntu or Debian, sometimes the original developers of the software have already found and fixed the issue, or at least @@ -231,7 +231,7 @@ Searching the upstream bug tracker, or generally Googling error messages or symptoms can sometimes turn up a patch or bug report of relevance. -### Forwarding issues upstream +## Forwarding issues upstream If there are no existing fixes for an issue, you can either develop one yourself, or communicate the problem to Debian or the upstream developers. diff --git a/docs/contributors/bug-fix/evalute-the-bug.md b/docs/contributors/bug-fix/evalute-the-bug.md index 41bda81d3..3e86288df 100644 --- a/docs/contributors/bug-fix/evalute-the-bug.md +++ b/docs/contributors/bug-fix/evalute-the-bug.md @@ -1,11 +1,11 @@ (evaluate-the-bug)= -## Evaluate the Bug +# Evaluate the Bug Let's look at an example: [bug #1753470 report](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470). -### Bug report description: +## Bug report description: The original bug report was filed with just this description: @@ -52,7 +52,7 @@ file, you can examine the to get a useful stacktrace. -### Try to reproduce the issue +## Try to reproduce the issue Not all bugs can be easily reproduced, and it's not always obvious how to reproduce even reproducible bugs. In these cases, some bug work will be needed @@ -80,7 +80,7 @@ many options for where and how to do your testing, and different developers have their own preferences. Here's a couple of options: -#### Make a test environment +### Make a test environment To make a container for testing: @@ -112,7 +112,7 @@ The "ubuntu" user's password is locked, but `sudo` can be run without password. ``` -#### Get up to date and install `postfix` +### Get up to date and install `postfix` ```none ubuntu@tester:~$ sudo apt dist-upgrade @@ -128,7 +128,7 @@ ubuntu@tester:~$ echo "virtual_alias_maps = pgsql:/etc/postfix/valiases.cf" \ ``` -#### To reproduce, the file must be unreadable by the current user +### To reproduce, the file must be unreadable by the current user ```none ubuntu@tester:~$ sudo touch /etc/postfix/valiases.cf @@ -136,7 +136,7 @@ ubuntu@tester:~$ sudo chmod 0600 /etc/postfix/valiases.cf ``` -#### Reproduce the issue +### Reproduce the issue ```none ubuntu@tester:~$ /usr/sbin/postconf virtual_alias_map diff --git a/docs/contributors/bug-fix/once-the-fix-is-accepted.md b/docs/contributors/bug-fix/once-the-fix-is-accepted.md index ed24204a4..b8b5ea1b7 100644 --- a/docs/contributors/bug-fix/once-the-fix-is-accepted.md +++ b/docs/contributors/bug-fix/once-the-fix-is-accepted.md @@ -1,8 +1,8 @@ (once-the-bugfix-is-accepted)= -## Once the bugfix is accepted +# Once the bugfix is accepted -### The acceptance email +## The acceptance email You'll receive an email notification that the bugfix was accepted: @@ -40,7 +40,7 @@ and make sure it's publishing to the correct place (Bionic), and that the builds completed (green check marks). -### The excuses page +## The excuses page Check the "excuses" or "migration" page, [for Bionic](https://ubuntu-archive-team.ubuntu.com/proposed-migration/bionic/update_excuses.html) @@ -57,7 +57,7 @@ This page is generated every few minutes, and doesn't update in real-time. ``` -### SRU verification +## SRU verification It's best to have the package independently verified (preferably by the person who reported the bug), but if it sits idle too long (2 days or so), you can diff --git a/docs/contributors/bug-fix/update-the-bug-report.md b/docs/contributors/bug-fix/update-the-bug-report.md index d2ac477d9..d8648f136 100644 --- a/docs/contributors/bug-fix/update-the-bug-report.md +++ b/docs/contributors/bug-fix/update-the-bug-report.md @@ -1,5 +1,5 @@ (update-the-bug-report)= -## Update the bug report +# Update the bug report For regular bug fixes and merges, adding a comment about your progress is typically all you'll need. You might provide some links to your PPA if you'd @@ -7,7 +7,7 @@ like to get people to test your fix, or if you want to provide the fix to the user-base swiftly. -### SRU paperwork +## SRU paperwork For stable release updates (SRUs), on the other hand, you need to add a bit more detail. @@ -38,7 +38,7 @@ the (`LP: #NNNNNN`) in the changelog entry. ``` -### SRU exceptions +## SRU exceptions There is a particular kind of [special case SRU](https://documentation.ubuntu.com/sru/en/latest/reference/package-specific/) From 2f12996c91fb83e3a5e5f0cb8dff9aa0bd089473 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Wed, 25 Mar 2026 19:37:21 +1300 Subject: [PATCH 14/18] fix: update the heading level --- docs/contributors/bug-fix/validate-the-fix.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/contributors/bug-fix/validate-the-fix.md b/docs/contributors/bug-fix/validate-the-fix.md index 646caad31..e7b20d266 100644 --- a/docs/contributors/bug-fix/validate-the-fix.md +++ b/docs/contributors/bug-fix/validate-the-fix.md @@ -1,8 +1,8 @@ (validate-the-fix)= -## Validate the fix +# Validate the fix -### Start a Bionic container and enter it: +## Start a Bionic container and enter it: We can name our LXC containers with any scheme we wish, such as 'tester' earlier for a temporary one to test with. However, for bug fixes we'll often @@ -22,7 +22,7 @@ root@postfix-sru-lp1753470-segfault-bionic:~# ``` -### Reproduce the bug +## Reproduce the bug Record your steps as you go (you'll need them later): @@ -38,7 +38,7 @@ Segmentation fault (core dumped) ``` -### Install the fixed package +## Install the fixed package In this case, I'm using a PPA. Alternatively, if you've built locally, you can copy in the `.deb` file and install it manually. @@ -50,7 +50,7 @@ $ sudo apt upgrade -y ``` -### Test the bug again +## Test the bug again ```none $ /usr/sbin/postconf virtual_alias_map From 68d7dfb7e45bf8ab894329884dbef2c86ed86404 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Wed, 25 Mar 2026 19:52:14 +1300 Subject: [PATCH 15/18] fix: update references to the new bugfix page --- .../processes/automatic-package-testing-autopkgtest.rst | 2 +- docs/how-ubuntu-is-made/processes/proposed-migration/index.md | 2 +- docs/how-ubuntu-is-made/processes/transitions.md | 2 +- docs/redirects.txt | 1 - docs/who-makes-ubuntu/developers/dmb-joining-packageset.md | 2 +- 5 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/how-ubuntu-is-made/processes/automatic-package-testing-autopkgtest.rst b/docs/how-ubuntu-is-made/processes/automatic-package-testing-autopkgtest.rst index 9cf74ebfd..a9edbf65c 100644 --- a/docs/how-ubuntu-is-made/processes/automatic-package-testing-autopkgtest.rst +++ b/docs/how-ubuntu-is-made/processes/automatic-package-testing-autopkgtest.rst @@ -162,7 +162,7 @@ well. Getting the test into Ubuntu ---------------------------- -The process of submitting an autopkgtest for a package is similar to :ref:`fixing a bug in Ubuntu `: +The process of submitting an autopkgtest for a package is described in :ref:`How to run package tests `: #. Run ``git ubuntu clone ``, #. Edit ``debian/control`` to enable the tests, diff --git a/docs/how-ubuntu-is-made/processes/proposed-migration/index.md b/docs/how-ubuntu-is-made/processes/proposed-migration/index.md index df87a7b2e..ee24e865c 100644 --- a/docs/how-ubuntu-is-made/processes/proposed-migration/index.md +++ b/docs/how-ubuntu-is-made/processes/proposed-migration/index.md @@ -14,7 +14,7 @@ special-migration-cases In Ubuntu there is a special {term}`pocket` called `-proposed` for testing and integration. In the following cases, packages are not automatically released to Ubuntu users, and instead go into the `-proposed` pocket: * New packages not already present in any Ubuntu release that have been automatically imported from Debian -* Uploads of {ref}`fixed ` packages. +* Uploads of {ref}`fixed ` packages. * Uploads of {ref}`merged ` packages. Once a package is deemed OK, it **migrates** into the `-release` pocket for users to consume. This is called the "proposed migration" process. diff --git a/docs/how-ubuntu-is-made/processes/transitions.md b/docs/how-ubuntu-is-made/processes/transitions.md index 2526b5145..dbc00f6db 100644 --- a/docs/how-ubuntu-is-made/processes/transitions.md +++ b/docs/how-ubuntu-is-made/processes/transitions.md @@ -99,7 +99,7 @@ The main complication you may run into during this phase are build failures. For example, upstream may have introduced some new dependencies not yet in the Ubuntu Archive. Resolving these issues can involve {ref}`MIRs `, pulling patches from upstream, and other -{ref}`how-to-fix-a-bug-in-a-package` activities. +{ref}`fixing-bugs` activities. (transitions-update-default-version)= diff --git a/docs/redirects.txt b/docs/redirects.txt index f31fa6999..3443f240f 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -97,7 +97,6 @@ how-to/download-new-upstream-version/ contributors/updating/get-a-new-upstream-v how-to/install-built-packages/ contributors/building/install-built-packages/ contributors/bug-fix/install-built-packages/ contributors/building/install-built-packages/ -how-to/propose-changes/ contributors/bug-fix/propose-changes/ how-to/run-tests/ contributors/building/run-package-tests/ contributors/bug-fix/package-tests/ contributors/building/run-package-tests/ diff --git a/docs/who-makes-ubuntu/developers/dmb-joining-packageset.md b/docs/who-makes-ubuntu/developers/dmb-joining-packageset.md index 38e0dbff7..ad259c824 100644 --- a/docs/who-makes-ubuntu/developers/dmb-joining-packageset.md +++ b/docs/who-makes-ubuntu/developers/dmb-joining-packageset.md @@ -33,7 +33,7 @@ In terms of the {ref}`uploaders-journey`, you should work your way through the s Ideally, you should have a solid mastery of the basic packaging skills for Debian/Ubuntu distributions, including the following: -* {ref}`Fixing bugs in packages ` +* {ref}`Fixing bugs in packages ` * Building binary packages from source, using `sbuild` or `debuild` in a `chroot` or `lxc` environment * Creating the initial packaging for new software From 80a7c39eb821ba4cd68aac247d1c167469664da3 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Wed, 25 Mar 2026 19:52:25 +1300 Subject: [PATCH 16/18] docs: redirect SRU link to SRU topic --- docs/who-makes-ubuntu/developers/dmb-joining-core-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/who-makes-ubuntu/developers/dmb-joining-core-dev.md b/docs/who-makes-ubuntu/developers/dmb-joining-core-dev.md index 1378e76b5..cbade186f 100644 --- a/docs/who-makes-ubuntu/developers/dmb-joining-core-dev.md +++ b/docs/who-makes-ubuntu/developers/dmb-joining-core-dev.md @@ -25,7 +25,7 @@ In terms of the {ref}`uploaders-journey`, MOTU are {ref}`experts ` and/or {ref}`MOTU ` membership. If you're skipping over those levels it is nevertheless worth reviewing their training and application processes to make sure you'll be fulfilling their requirements. -In addition to understanding common tasks documented in this guide, including {ref}`Debian patching `, {ref}`Stable Release Updates (SRUs) `, and so on, Core Dev applicants must also have a good understanding of these advanced packaging skills, and ideally direct experience with a few of them: +In addition to understanding common tasks documented in this guide, including {ref}`Debian patching `, {ref}`Stable Release Updates (SRUs) `, and so on, Core Dev applicants must also have a good understanding of these advanced packaging skills, and ideally direct experience with a few of them: * {ref}`Package sponsorship ` * {ref}`Seed handling ` From f06bc564947a6fce701efb82fee3e855bec8c978 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Wed, 25 Mar 2026 19:56:27 +1300 Subject: [PATCH 17/18] docs: validate-the-fix add the preface about container --- docs/contributors/bug-fix/validate-the-fix.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/contributors/bug-fix/validate-the-fix.md b/docs/contributors/bug-fix/validate-the-fix.md index e7b20d266..9d3933ae5 100644 --- a/docs/contributors/bug-fix/validate-the-fix.md +++ b/docs/contributors/bug-fix/validate-the-fix.md @@ -1,8 +1,11 @@ (validate-the-fix)= # Validate the fix +We need to validate the test in an isolated environment and LXC containers are a good tool for it. -## Start a Bionic container and enter it: +## Start a container + +For example when investigating a segfault for bionic, start a `bionic` container. We can name our LXC containers with any scheme we wish, such as 'tester' earlier for a temporary one to test with. However, for bug fixes we'll often From 371636b00367305c79c32f1d271bcaaeb5ae39e0 Mon Sep 17 00:00:00 2001 From: Vladimir Petko Date: Tue, 21 Apr 2026 09:35:35 +1200 Subject: [PATCH 18/18] docs: reference internal sru documentation --- docs/contributors/bug-fix/update-the-bug-report.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributors/bug-fix/update-the-bug-report.md b/docs/contributors/bug-fix/update-the-bug-report.md index d8648f136..6d4c118be 100644 --- a/docs/contributors/bug-fix/update-the-bug-report.md +++ b/docs/contributors/bug-fix/update-the-bug-report.md @@ -16,7 +16,7 @@ Go back to the [example bug report](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470). Modify the bug description (yellow pencil icon) and update it to conform with -[the SRU bug template](https://documentation.ubuntu.com/sru/en/latest/reference/bug-template/). +{ref}`the SRU bug template `. These are normally the "Impact", "Test Case" and "Where problems could occur" sections. @@ -41,7 +41,7 @@ the (`LP: #NNNNNN`) in the changelog entry. ## SRU exceptions There is a particular kind of -[special case SRU](https://documentation.ubuntu.com/sru/en/latest/reference/package-specific/) +{ref}`special case SRU ` which is called either a Minor Release Exception (MRE) or an SRU exception. In the former we assume upstream is so stable and similar to our needs, process and philosophy that fewer checks need to be done, in the latter we admit that @@ -54,7 +54,7 @@ stability, smooth upgradability, and other things important for an SRU. Each case is slightly different, which is why each of them gets their own discussion and their own accepted process listed in -[SRU special cases](https://documentation.ubuntu.com/sru/en/latest/reference/package-specific/) +{ref}`SRU special cases ` of how that particular minor release will be served. When we (in the server team) prepare special SRU updates they follow all the