Hello Russ, On Tue 18 Jun 2019 at 06:24PM -07, Russ Allbery wrote: > For those reading this, note that "recommended" is a documented keyword in > Policy, equivalent to "should." However, it is intentionally weakened > here with the "in the absence of a reason to use a different approach" > language. The goal here (and please judge whether I achieved it) is to > concentrate on providing default advice to people with no preference, > particularly people new to packaging, not to argue with maintainers who > are familiar with the tradeoffs and are intentionally making a different > choice. This seems like the right goal but I'm not sure your patch quite achieves it yet. > diff --git a/policy/ch-source.rst b/policy/ch-source.rst > index ee9270d..9ea2f5c 100644 > --- a/policy/ch-source.rst > +++ b/policy/ch-source.rst > @@ -259,18 +259,49 @@ files, sockets or setuid or setgid files.. [#]_ > Main building script: ``debian/rules`` > -------------------------------------- > > -This file must be an executable makefile, and contains the > -package-specific recipes for compiling the package and building binary > -package(s) from the source. > - > -It must start with the line ``#!/usr/bin/make -f``, so that it can be > -invoked by saying its name rather than invoking ``make`` explicitly. > -That is, invoking either of ``make -f debian/rules args...`` or ``./debian/rules args...`` must result in identical behavior. > +This file must be an executable makefile. It contains the > +package-specific recipes for compiling the source (if required) and > +constructing one or more binary packages. > + > +``debian/rules`` must start with the line ``#!/usr/bin/make -f`` so that > +it can be executed by running ``./debian/rules`` from the top of the > +source package. Invoking either of ``make -f debian/rules <arg> ...`` or > +``./debian/rules <arg> ...`` must result in identical behavior. I must admit to being sad to see the demise of "invoked by saying its name", but this is probably a sensible change. A tiny thing is that you seem to have switched "<args>" for "<arg>", which seems wrong. > + > +In the absence of a reason to use a different approach, the recommended > +way to implement the build process of a Debian package, including the > +contents of the ``debian/rules`` building script, is the ``dh`` tool, > +which is provided by the debhelper package. This is the most common > +packaging helper tool in Debian. Using it will save effort in complying > +with the rules in this document, since it will automatically implement > +many of them without requiring explicit instructions. I would like to try to make the first sentence normatively clearer. I think that it would be difficult to understand exactly what the project consensus is from that sentence, had you not read Sam's d-d-a post. Let me try to express what I think the problem is. What the first sentence says, given the equivalence of RECOMMENDED and SHOULD noted above, is "you should use dh unless there is a reason not to use dh". However, any SHOULD requirement in Policy implicitly has that structure: "you should X unless there is reason not to X". Perhaps MUST requirements don't have that implicit structure, because perhaps the idea in such cases is that there is never reason not to X. Thus, your sentence seems to just be making explicit something which is already implicit in any SHOULD requirement, i.e., "In the absence ..." is strictly redundant. And so I don't think the sentence succeeds in expressing the nuanced project consensus which it aims to express, because the consensus is more nuanced than just the implicit structure had by any SHOULD requirement. Would it be right to say that what we are trying to express is the idea that dh should be used when there aren't *package-specific* reasons not to use dh, and for new packages, we're recommending a workflow of starting with the assumption that no such package-specific reasons exist? This captures the idea that dh makes things easier for other contributors working on your package, which seems core to the project's consensus. > + > +There are various situations in which ``dh`` is not the best choice. For > +example, the standard tools for packaging software written in some > +languages may use another tool, some rarer packaging patterns (such as > +multiple builds of the same software with different options) are easier to > +express with other tools, or the packager may be working on a new > +packaging helper and may therefore want to use that tool. Using ``dh`` is > +therefore not required. But it is a wise default choice in most > +situations. > + > +If the package uses ``dh``, the default content of ``debian/rules`` will > +be:: I find the expression "default content" odd in this context, I think because defaults are things that executable programs have, not source code. Can I suggest we talk instead about the "starting point for the content of d/rules" and say something like "this starting point is often sufficient to build a package satisfying most of the requirements below (and many others), and where it is not, package-specific instructions are usually expressed using override targets" ? -- Sean Whitton
Attachment:
signature.asc
Description: PGP signature