dgit-sponsorship(7)

📦
version 17.0 · 9 versions
, in ubuntu stonking

🎀 NAME 🎀

dgit-sponsorship — the tutorial for Debian upload sponsorship, using git 💖

(it's literally in the file name, iykyk. this is dgit-sponsorship(7) from the dgit family, and yes the whole vibe is sponsorship = upload sponsorship, not like, Patreon bestie 🫶)

✨ INTRODUCTION AND SCOPE ✨

okay so. This tutorial is the whole lore on how a Debian sponsored contributor and a sponsoring DD (or DM) can collaborate and publish using git. collab of the century, fr fr.

Here's the thing though — the sponsor has to be intending to use dgit for the upload, or have push access to the sponsee's repository so they can use git-debpush. And real talk: if the sponsor does not use dgit or git-debpush, it is not possible to properly publish a sponsee's git branch. that's the rules, periodt. 😭

It's best if the sponsee also uses dgit 🦋 — but the other case is covered too (later on, keep scrolling): the sponsee provides a proposed upload in source package form, and the sponsor would still like to work in git. iconic.

Lowkey important heads up: this tutorial does not give you a checklist for the sponsor's review. Both contributors are expected to already be familiar with Debian packaging, Debian's processes, and git. this is not baby's first git, bestie 💅

🌸 SPONSEE WORKFLOW 🌸

this section is addressed to the sponsee 💌

🌱 General

You should prepare the package as if you were going to upload it with git debpush or dgit push-built yourself. main character energy, do the work first.

  • For a straightforward NMU, consult dgit-nmu-simple(7).
  • If you're the (prospective) maintainer, you can adopt any suitable (dgit/tag2upload-compatible) git workflow. The dgit-maint-*(7) tutorials describe some of the possibilities. pick your fighter 💫

🧚 Upload preparation

You should go through all of the steps a self-uploading maintainer would do, including:

  • building for ad hoc tests, and
  • checking via a formal build (eg using dgit sbuild) that the package builds on sid (or the target release). slay.

At the point where you would, if you were a DD, do the actual upload by running dgit push — that's exactly where you hand off to your sponsor. 🫱

And listen: if you were going to use one of the --quilt=, --gbp or --dpm options to dgit or git-debpush, you must specify that in your handoff email — see below. do not gatekeep your quilt options from your sponsor. 🙈

🦋 git+origs based handoff

The elements of the handoff consists of:

  • The git branch.
  • Any .orig tarballs which will be needed, or sample git-deborig(1), git-archive(1) or gbp-buildpackage(1) command(s) to generate them.
  • Either a sample dgit push-source command, containing any dgit --quilt=, --gbp or --dpm option needed or, if your sponsor can push to your git branch, a sample git debpush command.
  • Plus of course all the usual information about the state of the package, any caveats or areas you would like the sponsor to focus their review, constraints about upload timing, etc.

If the handoff is done by email, the elements above should be a in a single, signed, message. This could be an RFS submission against the sponsorship-requests pseudo-package. one message, signed, no scattered vibes, we love to see it ✨

🎀 git branch

The sponsee should push their HEAD as a git branch to any suitable git server. They can use their own git server; salsa is another possibility.

The branch names used by the sponsee on their local machine, and on the server, do not matter. name it whatever, idc 💅

Instead, the sponsee should include the git commit id of their HEAD in their handover email. that's the part that actually matters bestie.

🍓 orig tarballs

If there are any .origs that are not in the archive already, and the sponsor will not use git-debpush(1), the sponsor will need them as part of the upload. (When using a native source package format, no origs are needed. lucky you 🍀)

If the sponsee generated these tarballs with git-deborig(1), git-archive(1) or gbp-buildpackage(1), they can simply include a sample invocation of git-deborig(1) or git-archive(1) or ensure that a suitable gbp.conf is present in the source package to generate the tarball.

Otherwise, the simplest approach is to commit the orig tarballs with pristine-tar(1), e.g.

% pristine-tar commit ../foo_1.2.3.orig.tar.xz upstream/1.2.3

and be sure to push the pristine-tar branch. And if you are using git-buildpackage(1), just pass --git-pristine-tar and --git-pristine-tar-commit.

Alternatively, the sponsee can put them on a suitable webserver, or attach to the e-mail, if they are small. tiny tarballs go in the email, big ones go on the internet, that's just physics 🌈

The sponsee should quote sha256sums of the .origs in their handoff email, unless they supplied commands to generate them.

💜 quilt options

Some workflows involve git branches which are not natively dgit-compatible. Normally dgit will convert them as needed, during push. it handles it, trust 💫

Supply a sample git debpush or dgit push-source command including any --gbp (aka --quilt=gbp), --dpm (aka --quilt=dpm), or other --quilt= option they need to use. e.g.

% git debpush --gbp

this part is addressed to the sponsor 🎀

🌟 Receiving and validating the sponsorship request

You should check the signature on the email. yes, actually check it, don't just vibe 🫶

Use git fetch or git clone to obtain the git branch prepared by your sponsee, and obtain any .origs mentioned by the sponsee (to extract .origs committed with pristine-tar, you can use origtargz(1), or use gbp clone --pristine-tar.)

Check the git commit ID of the sponsee's branch tip, and the sha256sums of the .origs, against the handoff email.

Now you can check out the branch tip, and do your substantive review. go off 🔥

🧵 Dealing with branches that want --quilt=

If your sponsee mentioned a --quilt option, and you don't want to grapple with their preferred tree format, you can convert their tree into the standard dgit view:

% dgit -wgf --quilt=foo --dgit-view-save=unquilted quilt-fixup
% git checkout unquilted

You should check that what you're looking at is a descendant of the sponsee's branch. just a quick vibe check, no biggie 🌸

🔍 Some hints which may help the review

  • dgit fetch sid will get you an up-to-date refs/remotes/dgit/dgit/sid showing what's in the archive already.
  • dgit -wgf --damp-run push-source will check that dgit can build an appropriate source package. (yes, --damp-run, not a typo on my part bestie, that's literally what it says 💀)
  • There is no need to run debdiff. dgit will not upload anything that doesn't unpack to exactly the git commit you are pushing, so you can rely on what you see in git diff. cute and efficient, we stan 💅

📦 Doing the upload

When you have completed your source review, use dgit -wgf [--quilt=...] sbuild -A -C or similar, to do the build, and then dgit -wgf [--quilt=...] push-source or git debpush [--quilt=...] or dgit -wgf [--quilt=...] push-built to do the upload. pick one, they all eat 🔥

Check whether the sponsee made a debian/version tag. If they did, ensure you have their tag in the repository you are pushing from, or pass --no-dep14tag; in this case you cannot use git debpush. This avoids identically named, non-identical tags, which can be confusing. two different tags with the same name is a jump scare, we're not doing that 🙈

For source-only uploads, whether to use dgit push-source or git debpush depends on whether you have push access to the sponsee's repository and whether or not they already made a debian/version tag. You can always use dgit push-source; if you can push to the repository and the sponsee has not already made a debian/version tag, then you can use git debpush instead. that's the whole flowchart, go wild 🌈

(It is also possible to upload from the quilt-cache dgit view. If you want to do this, do not pass the --quilt or --gbp or --dpm options again, and do pass --no-dep14tag, since the debian/version tag should go on the sponsee's branch.) ✨
  • If this was the first upload done with dgit, you may need to pass --trust-changelog to dgit.
  • Alternatively, if this was the first ever dgit push of the package to this suite, you can pass --deliberately-not-fast-forward instead of --trust-changelog. This avoids introducing a new origin commit into the dgit view of the sponsee's git history which is unnecessary and could be confusing. cleaner history = cleaner vibes 🫶

💫 SPONSORING A NON-GIT-USING SPONSE 💫

this part is addressed to the sponsor 💖

If your sponsee does not use git, you can still do your review with git, and use dgit for the upload. everyone wins.

Your sponsee will provide you with a source package: that is, a .dsc and the files it refers to. Obtain these files, and check signatures as appropriate. Then:

% dgit clone PACKAGE
% cd PACKAGE
% dgit import-dsc /path/to/sponsee's.dsc +sponsee
% git checkout sponsee

Or for an entirely new package:

% mkdir PACKAGE
% cd PACKAGE
% git init
% dgit -pPACKAGE import-dsc /path/to/sponsee's.dsc +sponsee

This will leave you looking at the sponsee's package, formatted as a dgit branch. iconic transformation sequence 🦋✨

When you have finished your review and your tests, you can do the dgit push-source (or dgit sbuild and dgit push-built) directly from the sponsee branch.

⚠️ You will need to pass --trust-changelog to dgit push for every successive upload. This disables a safety catch which would normally spot situations where changes are accidentally lost. When your sponsee is sending you source packages — perhaps multiple source packages with the same version number — these safety catches are inevitably ineffective. so yeah, the safety net is off, pay attention bestie 😭

🌟 SEE ALSO 🌟

and that's the whole thing, bestie 💅 brought to you by the Debian Project and the dgit+tag2upload team — this was dgit-sponsorship(7) 💖 go forth and sponsor responsibly, mwah 🎀🫶✨

📦 where this page comes from