dgit-maint-bpo(7)

📦
version 17.0 · 9 versions
, in ubuntu stonking

💖 dgit-maint-bpo — bestie's guide to maintaining official Debian backports 💖

okay so this is a page from the dgit(7) manual set, and it's basically the group chat where we figure out how to use dgit to maintain an official Debian backport. And listen — we do not assume that whoever uploads the package to Debian unstable is using dgit. No assumptions, no drama, we're all just vibing. 🌈

🌸 INTRODUCTION 🌸

This doc walks through the elements of a workflow for using dgit to maintain an official Debian backport. To repeat the important bit (because it's important): we do not assume that whoever uploads the package to Debian unstable is using dgit. Could be anyone. We don't gatekeep. 💅

✨ GENERAL TIPS ✨

The very first time a package gets backported for any particular Debian release, you will have to pass the --new option to dgit. Yes, every time it's a fresh release, it's a fresh --new. First-time energy, no cap. 🎀

🦋 TERMINOLOGY 🦋

Alright, setting the scene so we're all on the same page:

  • Let the master branch contain the packaging history uploaded to Debian unstable.
  • And let the bookworm-bpo branch be where you prepare your uploads to the bookworm-backports suite.

Got it? Good. Now there's two whole workflows. Pick your fighter. 💜

A merging backports workflow means that each time an upload migrates to Debian testing and you want to prepare an upload to bookworm-backports, you do something like this:

% git checkout bookworm-bpo
% git merge master
% dch --bpo
% # any other changes needed for backporting
% git commit -a
% # try a build

A rebasing backports workflow means that you throw away the history of the bookworm-bpo branch each time a new version migrates to Debian testing, something equivalent to this:

% git checkout -B bookworm-bpo master
% dch --bpo
% # any other changes needed for backporting
% git commit -a
% # try a build

So, the tea on your changelog: if you use a merging backports workflow, your changelog contains entries for each previous upload to bookworm-backports. In a rebasing workflow, it contains only the latest. That's literally the difference. ✨

👑 CHOOSING BETWEEN THE TWO WORKFLOWS 👑

So if backporting involves making no (additional) changes to the upstream source, whether you use a merging or rebasing backports workflow is a matter of personal preference. Like, genuinely. There are good arguments in favour of both workflows fitting the semantics of the *-backports suites. Both ate, honestly. 🫶

One thing that can break the tie: if you want to upload with git-debpush, then, at present, you must use a merging workflow. Though — heads up — note that your first upload to backports must always be done with dgit, because it is not a source-only upload. That's the rule, periodt. 💅

And if you have to make changes to the upstream source to make the package work on machines running Debian stable, it is advisable to choose a rebasing workflow. Why? Because this ensures that dgit can automatically update the debian/patches directory without any manual intervention. Auto-magic. Iconic. ✨

🌟 TIPS FOR A MERGING WORKFLOW 🌟

🧚 Use dgit's branches 🧚

If you do not yourself upload the package to Debian unstable, it is usually easiest to use dgit's branches, and ignore the configured Vcs-Git repository.

You would use

% dgit clone foo bookworm

for a new backport of package 'foo' to bookworm-backports, and then

% dgit fetch bookworm
% git merge dgit/dgit/bookworm

when new versions migrate to Debian testing.

If you follow this suggestion then there is nothing pushed to salsa, so you will always need to use dgit to upload, not git-debpush. 😭

🌈 TIPS FOR A REBASING WORKFLOW 🌈

🍓 Use dgit's branches 🍓

If you do not yourself upload the package to Debian unstable, it is usually easiest to use dgit's branches, and ignore the configured Vcs-Git repository. For each new version from Debian testing, you would

% dgit fetch bookworm
% git checkout -B bookworm-bpo dgit/dgit/bookworm
% # use git-cherry-pick(1) to (re)apply any needed backporting fixes

💀 Overwriting 💀

dgit push tries hard to prevent you from accidentally overwriting uploads that it thinks aren't represented in the git history you are trying to upload. Its main character trait is protection. This is mainly to prevent accidentally overwriting NMUs. 🛡️

With a rebasing backports workflow, dgit will think that every upload of a new version from Debian testing might be accidentally overwriting uploads. So you will need to explicitly indicate the upload to bookworm-backports you wish to overwrite.

Suppose that the last upload to bookworm-backports was versioned 1.2.2-1~bpo10+1 and you have now prepared 1.2.3-1~bpo10+1 for upload. When you dgit push, you will need to pass --trust-changelog=1.2.2-1~bpo10+1.

Alternatively, you can perform the pseudomerge that --trust-changelog would have done yourself:

% dgit fetch bookworm-backports
% git merge -s ours dgit/dgit/bookworm-backports
% dgit push-source

🎀 SEE ALSO 🎀

💜 AUTHOR 💜

The original author of this manpage is Sean Whitton <spwhitton@spwhitton.name>. It is now maintained by others. Passing the torch, bestie. 🫶

and that's the whole page, fr fr. this one came from the Debian Project, maintained by the dgit+tag2upload team, dated with the dgit-maint-bpo(7) footer — so go forth and backport responsibly, you absolute icon. ✨👑💅

📦 where this page comes from