Axel’s Tips and Tricks for Mentees

About

This page contains my (personal) tips and tricks for mentees so that they get the upload of their packages into the Debian archive sponsored by me.

If you’re interested in having me as sponsor for some of your packages, I’d be happy if you would have a look at this page and try to follow these requirements, recommendations and suggestions.

Contact

Contact me on IRC (XTaran on OFTC, Freenode, (German) IRCNet, LUGS IRC Network, Chaostreff.ch IRC Network, …), by e-mail (abe@debian.org) or in real life.

Information nice to know before reviewing the package

• Are you interested in long-term or one-time sponsorship?
• Is the package team-maintained? Did you already ask the team to sponsor it?
• Do you have DM upload permissions for other packages?

The Debian Version

Packages uploaded to Debian should have successive Debian versions. Especially packages containing new upstream versions should end in either a -1 or lower (e.g. for NMUs or upload to experimental).

• So please don’t increment the debian version every time you send an updated package to me or every time you upload it to mentors.debian.net.
• Use Debian version suffixes starting with ~, e.g. -1~mentors1, -1~test1, or -1~dev1 in case you prefer to upload only distinct versions to mentors.debian.net. Nevertheless do merge their changelogs for the final version.
• Exceptions are fine, if the package has been published already in a public APT repo elsewhere, e.g. at your company, in your PPA or your self-hosted and public APT repository. Using a ~ based suffix for versions in those repositories is appreciated, though.

Automated Checks

• Run licensecheck from the devscripts package. Does it show anything unexpected? Are all found licenses DFSG-compliant?
• Run lintian -L '>=pedantic/wild-guess' on the .changes file or instruct debuild to do so automatically.
• If you don’t know what the warnings mean, either pipe them through lintian-info or add the --info option.
• This also enables Lintian’s informational and pedantic checks. I have them enabled, too, and hence I may ask you to fix some of them.
• Source and binary packages should be “lintian clean”. If not, you should be able to explain why.
• In case of lintian argues about typos or syntax issues in man-pages, please try to fix them by adding a patch. If you successfully created a patch, please also forwarded it to upstream (in case the man page has been written by upstream).
• If part of the packaged software is written in C, C++ or similar, run the Build Log Hardening Checker blhc from the blhc package and the standalone Build Log Scanner from the package bls-standalone.
• If the package is already in Debian, check its PTS page: Does it mention any todos?
• Install your freshly built packages and check the installed packages with adequate to check for common errors which become only visible if the package is installed.

Common Checks

• Does upgrading from the previous version work?
• Would upgrading from the version in the current stable release of Debian work?
• Run debdiff over the previous and the current source packages. Anything unexpected?
• Run debdiff over all binary packages of the previous and the current source packages. Anything unexpected?

Non-Native Only Checks

• Does it have a watch file? Does it work?
• Does upstream provide a test suite? Does it run at build-time? Does it obey nocheck? (Or just use dh_auto_test and no more care about the correct usage of the test suite. :-)

Things I Care About

… and you should, too. ;-)

• The clean target should restore the source package into the same state as it was at unpack time. Having the package in VCS helps here.
• If upstream uses “autotools”, make sure to either use dh_autotools-dev_updateconfig and dh_autotools-dev_restoreconfig or dh_autoreconf and dh_autoreconf_clean.
  • The package should definitely update config.guess and config.sub at build-time, i.e. build-depend on autotools-dev (either directly or indirectly via dh-autoreconf)
  • Don’t copy config.guess and config.sub manually in the debian/rules file unless you have a very good reason for not using dh_autotools-dev_updateconfig and dh_autotools-dev_restoreconfig.
• Don’t remove stamp files manually in debian/rules. Use dh_clean and debhelper compatibility level 7 or higher.
• All changes on files in the debian directory should be documented in the package’s changelog. Details may be left out on bigger changes which obviously change those things not mentioned.
  • If you bump Standard-Version or the debhelper compatibility level, always mention to which level you switch.
• Packages listed in Depends should be real hard dependencies. All optional dependencies go either into Recommends or Suggests, even if there are people which are annoyed because their use-case didn’t work out-of-the-box, because they disabled pulling in recommended packages by default.
• Honor dpkg’s build flags, i.e. hardening flags. Using dh_auto_configure, dh_auto_build and debhelper compatibility ≥ 9 often helps already a lot here.
• Do not use programming-language-specific binary package names and sections if you’re packaging an application or service:
  • Do not use section python and/or binary package prefix python- if you’re packaging a python-written application or service.
  • Do not use section ruby and/or binary package prefix ruby- if you’re packaging a ruby-written application or service.
  • Do not use section perl and/or a binary package name of the scheme lib*-perl if you’re packaging a perl-written application or service.
• Run duck, the Debian Url ChecKer over your source package.

Non-Native Only Things

• Maintain a good relationship with upstream.
• If upstream ships a changelog, install it into the package with dh_installchangelogs
• Don’t list upstream changes in the debian/changelog unless
  • they require packaging changes
  • they fix bugs reported against Debian
  • they fix security issues
• Always mention what the new upstream version fixes if it fixes bugs reported in Debian. This means that you must not close bugs fixed by a new upstream version just with “New upstream version (Closes: #)” in the changelog if the bug report itself wasn’t named “New upstream version available” (or equivalent).
• Please avoid repackaging.
• Valid reasons for repackaging are:
  • Non-DFSG-compliant files in the upstream tar-ball
  • Non-tar upstream source distribution
  • Excluding embedded libraries
  • Broken upstream tar balls (dpkg is picky at that point :-)
• Source packages with repackaged upstream tar ball should include
  • a README.source documenting why and how the upstream tar-ball has been repackaged.
  • a get-orig-source target in debian/rules which does repackaging (and optionally the downloading, too)

Nice to Have

• Use a Debian-hosted VCS (e.g. on Alioth, if not team-maintained preferably in collab-maint)
• You already built the package in pbuilder to verify that all the build-dependencies are listed in the source package.
• Source Format “3.0 (native)” or “3.0 (quilt)”.
• Machine-readable debian/copyright format 1.0

Packages Not Yet in Debian

• File an “Intent to Package” aka ITP.
• Check upstreams code for mentioned licenses or files without obvious license. Just looking at the file named COPYING or LICENSE does not count. Upstream may have copied some code from other sources and did not mention it in their documentation.
• Check if upstream already provides some Debian packages. If so, contact them and try to base your work on theirs. Possibly maintain the package together with them.
• Check if someone already packaged the software for Ubuntu, i.e. in some PPA. If so, contact the person and ask if (s)he would like to maintain the package for Debian together with her/him. Try to base your work on hers/his.

Don’t be shy

(Applies if I already agreed to sponsor your packages.)

• If you don’t know how to meet some of the criteria mentioned in here, feel free to ask.
• If have no idea where to start, check mentors.debian.net’s Introduction for maintainers first. If that doesn’t help, feel free to ask.

Providing the source package to me

• Please always sign the package when you provide the package to me: Use debuild without -us -uc or use pdebuild --auto-debsign.
• I don’t need binary packages, but it’s perfectly ok, if you build both, source and binary packages, when providing them to me.
• I prefer dgetable .dsc files, but a pointer to some VCS is fine, too, if that VCS also provides the upstream tar-balls via pristine-tar, preferably imported with git-import-orig from the git-buildpackage package.

Personal Preferences

This is a list of things which I prefer, so I tend to sponsor a package more likely if fits into these preferences.

• I prefer Git as VCS
• I prefer VCS with pristine-tar branch.
• I like programming in Perl, hence sponsoring Perl stuff is no issue at all.
• I prefer debhelper (old and new style) over CDBS
• I prefer as minimal as possible debian/rules files, i.e. as much as possible is done via defaults and like needs less maintenance when the defaults change in the future.
• I prefer debhelper compatibility ≥ 9. I consider any compatibility level < 7 as deprecated.
• For source format 1.0 packages I prefer quilt over dpatch over direct changes in the Debian .diff.gz.

References

• Debian Wiki: SponsorChecklist
• FTP-Master: REJECT FAQ

Thanks

Thanks to Paul Tagliamonte for inspiring this document with his Sponsoring Guildines and Mattia Rizzolo for further suggestions.

Generated with Pandoc’s Markdown plugin.