Bug#802501: Concluding "What should happen when maintscripts fail to restart a service?"

[Gunnar Wolf]

Hello Sean,

> In #904558 I asked the T.C. for advice about how to move #802501
> forward.  Their ultimate response was to recommend that a working group
> of developers come up with some method, other than exiting nonzero, for
> a maintscript to indicate that it failed to restart services.  Let me
> take this opportunity to thank all those who were involved in #904558.
> 
> In this message, I seek to explain my understanding of what the closing
> of T.C. bug #904558 means for debian-policy bug #802501, and those
> merged with it.  Apologies for the length.  I wanted this general sort
> of reasoning to be recorded somewhere for reference in future
> discussions.

Thank you for providing this framing and for helping us (me, at
least!) better understand the circumstances of your bug filing. Quite
probably, I should have probably read #802501 during the #904558
discussion (and it's a very short bug FWIW), but didn't. Understanding
the bug follow-up policy of the Policy Editors makes me more at ease
with what we (TC) decided — We were not the first ones to fail to find
an always-good solution :-|

Now, I would more than welcome this bugs to be pushed to the right
areas: To d-devel, or to a new, specialized working group tackling the
issue. Both in the bugs and in our discussions, it is often repeated
(quoting here Sam, from #802501) «as a distribution, I think we should
explicitly encourage people to consider the consequences on
dist-upgrade and other operations». Inconsistently failing is *not*
OK, and nobody implied it that way...

So,

> The 'obsolete', 'ctte' and 'stalled' usertags are meant to be used in
> addition to the 'wontfix' tag.
> 
> ~ ~ ~
> 
> In #904558, I did not ask the T.C. to rule on what maintscripts should
> do when they fail to restart a service.  Rather, I asked them to weigh
> in on the decision between the options described above, given that the
> Policy Changes Process had failed to achieve consensus.  However, in the
> message closing #904558, the T.C. indicated that they declined to issue
> a ruling about what maintscripts should do when they fail to restart a
> service.  So the second option described above, corresponding to the
> 'ctte' usertag, has been taken off the table.
> 
> That leaves us with the question of whether to leave #802501 open, in
> the absence of the possibility of closing it by having the T.C. make a
> call.  Given that this bug has already been filed (at least) twice, I
> think it would be best for us to leave it open.  So I'm tagging
> wontfix+stalled.

I want to interpret this wontfix+stalled, and the TC answer ("The
Technical Committee does not engage in design of new proposals and
policies") don't mean this problem will just lay dormant and unsolved
forever. As Marga said in her mail closing this bug, «While we
recognize that this is a problem worth fixing, this is not something
that we can fix as a body and need the help of the Developers to do
it.»

I want to insist on our recommendation to create a work group of
developers to tackle this issue. Maybe we can start it off as a BoF
session in DC19?


signature.asc
Description: PGP signature

Bug#930666: Please document consensus on use of dh sequencer

[Russ Allbery]

Sean Whitton  writes:

>> --- 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  ...`` or
>> +``./debian/rules  ...`` 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.

I probably shouldn't have muddled this patch with the wording
clarification, but I found the previous text a bit confusing.  It's a nice
turn of phrase, but I've never seen anyone elsewhere refer to running a
script via a relative path as "saying its name."

> A tiny thing is that you seem to have switched "" for "",
> which seems wrong.

I'll put this back to args... since it just muddles the discussion, and we
can talk about that separately some other time.  But, for the record,
"" would imply that all the arguments have to be given as a single
argument and would be later split, as opposed to " ...", which allows
for one or more arguments.

> 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.

I agree with Sam that this is not the way Policy is currently written.
This *is* what RFC 2119 SHOULD means, but this is one of the places where
Policy diverges from RFC 2119.  We say:

| Non-conformance with guidelines denoted by *should* (or *recommended*)
| will generally be considered a bug, but will not necessarily render a
| package unsuitable for distribution.

which isn't as clear as it could be, but doesn't leave clear room for
maintainer discretion or other reasons, just a lot of room for severity.
Compare to RFC 2119:

| This word, or the adjective "RECOMMENDED", mean that there may exist
| valid reasons in particular circumstances to ignore a particular item,
| but the full implications must be understood and carefully weighed
| before choosing a different course.

which is much weaker than Policy should.

> 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?

I don't think so, since this doesn't account for a maintainer who is
writing a new packaging helper, which is not a package-specific reason
(it's a maintainer-specific reason).  I also don't think the project
consensus was to tell Jonas (the cdbs maintainer) to use dh for all new
packages.

I understand the concern about making the language too weak, but I also
don't think there's a need to be too firm here.  The goal, at least as I
see it, is to push people who don't have strong opinions towards dh, not
to try to convince the people who do have strong opinions.  (I think that
convincing is worthwhile but I think it will happen organically and Policy
isn't really the place.)

> 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" ?

That sounds great to me.  I'll make that change in my draft.

-- 
Russ Allbery (r...@debian.org)   

Bug#930666: Please document consensus on use of dh sequencer

[Russ Allbery]

Bill Allombert  writes:
> On Tue, Jun 18, 2019 at 06:24:45PM -0700, Russ Allbery wrote:

>>  The following targets are required and must be implemented by
>>  ``debian/rules``: ``clean``, ``binary``, ``binary-arch``,
>> -``binary-indep``, ``build``, ``build-arch`` and ``build-indep``. These
>> -are the targets called by ``dpkg-buildpackage``.
>> +``binary-indep``, ``build``, ``build-arch`` and ``build-indep``.  (When
>> +using ``dh``, these are implemented using the wildcard pattern shown
>> +above.)  These are the targets called by ``dpkg-buildpackage``.

> Hello Russ,

> I find this layering violation rather confusing especially if dh should
> be seen as the rule and not the exception.

> There are maybe an hundred places where we could mention dh,
> with statement like "when using dh, do something else".

I think there are fewer of them than you might think (I had that
impression too going in, but found that there were a lot fewer than I had
expected), but I also think that making those changes going forward will
be valuable.  We've already started doing that with debhelper, largely in
footnotes, and having a more systematic way of structuring that would be
useful.  I think this may be usefully expressed in metadata: some way to
flag a section of Policy with "debhelper does this for you" (since in most
cases it doesn't matter if you're using debhelper directly or via dh).

That said, this is way too large of a problem to solve in this bug.  I
think we need to stay focused on one section of policy here with a few
tactical fixes so that the text still reads cleanly and not confusingly
(which is the goal above), and then look at what we can do elsewhere to
spread the clarity once we've agreed on what we want to say here.

> Maybe what we need is a separate 'dh packaging manual' where packaging
> is explained from dh point of view.

That already exists, I think?  That's the debhelper documentation.

Another option would be to leave out the minimal debian/rules example
entirely and just refer entirely to the dh manual.  Maybe that's better.

-- 
Russ Allbery (r...@debian.org)   

Processed: Re: Bug#761219: debian-policy: document versioned Provides

[Debian Bug Tracking System]

Processing control commands:

> tag -1 -patch +pending
Bug #761219 [debian-policy] debian-policy: document versioned Provides
Removed tag(s) patch.
Bug #761219 [debian-policy] debian-policy: document versioned Provides
Added tag(s) pending.

-- 
761219: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=761219
Debian Bug Tracking System
Contact ow...@bugs.debian.org with problems

Bug#761219: debian-policy: document versioned Provides

[Sean Whitton]

control: tag -1 -patch +pending

Hello,

On Thu 20 Jun 2019 at 04:43pm +0200, gregor herrmann wrote:

> Seconded as well.

Thanks.  Applied.

-- 
Sean Whitton

Bug#802501: Concluding "What should happen when maintscripts fail to restart a service?"

[Sean Whitton]

tag 802501 + wontfix
user debian-pol...@packages.debian.org
usertag 802501 = normative stalled
thanks

Hello,

In #904558 I asked the T.C. for advice about how to move #802501
forward.  Their ultimate response was to recommend that a working group
of developers come up with some method, other than exiting nonzero, for
a maintscript to indicate that it failed to restart services.  Let me
take this opportunity to thank all those who were involved in #904558.

In this message, I seek to explain my understanding of what the closing
of T.C. bug #904558 means for debian-policy bug #802501, and those
merged with it.  Apologies for the length.  I wanted this general sort
of reasoning to be recorded somewhere for reference in future
discussions.

~ ~ ~

When the Policy Changes Process fails to establish consensus, we have a
few options.  If we think that consensus hasn't been established only
because no-one has volunteered to come up with an adequately detailed
response to the problem uncovered by the filing and discussion of the
bug, and the bug has been open for a while with no evidence of anyone
working on it, we (the Policy Editors) will often just close the bug.
We don't want such things to stick around, clogging up the list of open
issues in a way that's demotivating.  This is the 'obsolete' usertag.

If we think that consensus hasn't been established because there are
good arguments on all sides, but we (the Policy Editors) additionally
think that argument to determine the very best solution is less
important right now than settling on one of the possible solutions
rather than remaining in further discussion, then we can refer the bug
to the T.C. to make a call between the competing options.  This was, I
think, the intended purpose of the 'ctte' usertag, but we haven't been
using it.

Finally, if we don't want to refer the bug to the T.C. -- generally
because it's not important enough -- but we think that closing the bug
would be counterproductive because someone else will just open a new bug
raising the same issue again at some near point in time, we can just
leave the bug open, as a kind of placeholder to hopefully reduce the
number of duplicate bugs filed.  I just added a 'stalled' usertag for
this case.

The 'obsolete', 'ctte' and 'stalled' usertags are meant to be used in
addition to the 'wontfix' tag.

~ ~ ~

In #904558, I did not ask the T.C. to rule on what maintscripts should
do when they fail to restart a service.  Rather, I asked them to weigh
in on the decision between the options described above, given that the
Policy Changes Process had failed to achieve consensus.  However, in the
message closing #904558, the T.C. indicated that they declined to issue
a ruling about what maintscripts should do when they fail to restart a
service.  So the second option described above, corresponding to the
'ctte' usertag, has been taken off the table.

That leaves us with the question of whether to leave #802501 open, in
the absence of the possibility of closing it by having the T.C. make a
call.  Given that this bug has already been filed (at least) twice, I
think it would be best for us to leave it open.  So I'm tagging
wontfix+stalled.

~ ~ ~

In filing #904558, I made an alternative suggestion to the above:

> As a Policy delegate I want to move this issue along, and I can see
> three ways of doing that:
>
> 1. write a patch to explicitly state in Policy that what happens when a
>service (re)start fails in a maintscript is left up to package
>maintainer discretion, and close the bugs
> [...]

I no longer think this would be useful enough to have in Policy, but I'd
like to hear from anyone who disagrees.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Processed: Concluding "What should happen when maintscripts fail to restart a service?"

[Debian Bug Tracking System]

Processing commands for cont...@bugs.debian.org:

> tag 802501 + wontfix
Bug #802501 [debian-policy] init script failures during postinst and related 
scripts
Bug #780403 [debian-policy] debian-policy: Define what should happen when 
installing a package and the init script fails to start it
Added tag(s) wontfix.
Added tag(s) wontfix.
> user debian-pol...@packages.debian.org
Setting user to debian-pol...@packages.debian.org (was 
spwhit...@spwhitton.name).
> usertag 802501 = normative stalled
Usertags were: discussion normative.
Usertags are now: normative stalled.
> thanks
Stopping processing here.

Please contact me if you need assistance.
-- 
780403: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=780403
802501: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=802501
Debian Bug Tracking System
Contact ow...@bugs.debian.org with problems

Bug#761219: debian-policy: document versioned Provides

[gregor herrmann]

On Thu, 20 Jun 2019 11:00:58 +0100, Sean Whitton wrote:

> On Fri 07 Jun 2019 at 10:50AM +01, Dominic Hargreaves wrote:
> 
> > diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
> > index 1d790e8..3b68420 100644
> > --- a/policy/ch-relationships.rst
> > +++ b/policy/ch-relationships.rst
> > @@ -17,15 +17,16 @@ package names, separated by vertical bar (pipe) symbols 
> > ``|``. In such a
> >  case, that part of the dependency can be satisfied by any one of the
> >  alternative packages.  [#]_
> >
> > -All of the fields except for ``Provides`` may restrict their
> > -applicability to particular versions of each named package. This is done
> > -in parentheses after each individual package name; the parentheses
> > -should contain a relation from the list below followed by a version
> > -number, in the format described in :ref:`s-f-Version`.
> > +All of the fields may restrict their applicability to particular versions
> > +of each named package. This is done in parentheses after each individual
> > +package name; the parentheses should contain a relation from the list
> > +below followed by a version number, in the format described in
> > +:ref:`s-f-Version`.
> >
> >  The relations allowed are ``<<``, ``<=``, ``=``, ``>=`` and ``>>`` for
> >  strictly earlier, earlier or equal, exactly equal, later or equal and
> > -strictly later, respectively.  [#]_
> > +strictly later, respectively. The exception is the Provides field, for
> > +which only ``=`` is allowed.  [#]_
> >
> >  Whitespace may appear at any point in the version specification subject
> >  to the rules in :ref:`s-controlsyntax`, and must appear
> > @@ -446,17 +447,43 @@ they can say:
> >  and the ``bar-plus`` package will now also satisfy the dependency for
> >  the ``foo`` package.
> >
> > -If a relationship field has a version number attached, only real
> > -packages will be considered to see whether the relationship is satisfied
> > -(or the prohibition violated, for a conflict or breakage). In other
> > -words, if a version number is specified, this is a request to ignore all
> > -``Provides`` for that package name and consider only real packages. The
> > -package manager will assume that a package providing that virtual
> > -package is not of the "right" version. A ``Provides`` field may not
> > -contain version numbers, and the version number of the concrete package
> > -which provides a particular virtual package will not be considered when
> > -considering a dependency on or conflict with the virtual package name.
> > -[#]_
> > +A ``Provides`` field may contain version numbers, and such a version number
> > +will be considered when considering a dependency on or conflict with the
> > +virtual package name.  [#]_ For example, given the following packages:
> > +
> > +::
> > +
> > +Package: foo
> > +Depends: bar (>= 1.0)
> > +
> > +Package: bar
> > +Version: 0.9
> > +
> > +Package: bar-plus
> > +Provides: bar (= 1.0)
> > +
> > +the ``bar-plus`` package will again satisfy the dependency for
> > +the ``foo`` package with the virtual package name.  [#]_ If the 
> > ``Provides``
> > +field does not specify a version number, it will not satisfy versioned
> > +dependencies or violate versioned ``Conflicts`` or ``Breaks``. For example,
> > +given the following packages:
> > +
> > +::
> > +
> > +Package: foo
> > +Depends: bar (>= 1.0)
> > +
> > +Package: bar
> > +Version: 0.9
> > +
> > +Package: bar-plus
> > +Provides: bar (= 1.0)
> > +
> > +Package: bar-clone
> > +Provides: bar
> > +
> > +the ``bar-plus`` package will satisfy the dependency for the ``foo``
> > +package, but the ``bar-clone`` package will not.
> >
> >  To specify which of a set of real packages should be the default to
> >  satisfy a particular dependency on a virtual package, list the real
> > @@ -670,10 +697,8 @@ dependencies.
> > together and then configured in their dependency order.
> >
> >  .. [#]
> > -   It is possible that a future release of ``dpkg`` may add the ability
> > -   to specify a version number for each virtual package it provides.
> > -   This feature is not yet present, however, and is expected to be used
> > -   only infrequently.
> > +   This functionality was introduced in dpkg 1.17.11 and newer and
> > +   full support has been provided in the Debian archive since 2018.
> >
> >  .. [#]
> > To see why ``Breaks`` is normally needed in addition to ``Replaces``,
> 
> Seconded.  Thank you again.

Seconded as well.


Cheers,
gregor

-- 
 .''`.  https://info.comodo.priv.at -- Debian Developer https://www.debian.org
 : :' : OpenPGP fingerprint D1E1 316E 93A7 60A8 104D  85FA BB3A 6801 8649 AA06
 `. `'  Member VIBE!AT & SPI Inc. -- Supporter Free Software Foundation Europe
   `-   NP: U2: With our Without You


signature.asc
Description: Digital Signature

Bug#930666: Please document consensus on use of dh sequencer

[Bill Allombert]

On Tue, Jun 18, 2019 at 06:24:45PM -0700, Russ Allbery wrote:
>  The following targets are required and must be implemented by
>  ``debian/rules``: ``clean``, ``binary``, ``binary-arch``,
> -``binary-indep``, ``build``, ``build-arch`` and ``build-indep``. These
> -are the targets called by ``dpkg-buildpackage``.
> +``binary-indep``, ``build``, ``build-arch`` and ``build-indep``.  (When
> +using ``dh``, these are implemented using the wildcard pattern shown
> +above.)  These are the targets called by ``dpkg-buildpackage``.

Hello Russ,

I find this layering violation rather confusing especially if dh should
be seen as the rule and not the exception.

There are maybe an hundred places where we could mention dh,
with statement like "when using dh, do something else".

Maybe what we need is a separate 'dh packaging manual' where packaging
is explained from dh point of view.

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 

Bug#930666: Please document consensus on use of dh sequencer

[Sam Hartman]

> "Sean" == Sean Whitton  writes:

Sean> Let me try to express what I think the problem is.  What the
Sean> first sentence says, given the equivalence of RECOMMENDED and
Sean> SHOULD noted above, is "you should use dh unless there is a
Sean> reason not to use dh".

Sean> However, any SHOULD requirement in Policy implicitly has that
Sean> structure: "you should X unless there is reason not to X".


That's not how I read policy at all.
>In the normative part of this manual, the words *must*, *should* and
>*may*, and the adjectives *required*, *recommended* and *optional*,
>are used to distinguish the significance of the various guidelines in
>this policy document. Packages that do not conform to the guidelines
>denoted by *must* (or *required*) will generally not be considered
>acceptable for the Debian distribution. Non-conformance with
>guidelines denoted by *should* (or *recommended*) will generally be
>considered a bug, but will not necessarily render a package unsuitable


No where in the above text do I see that if there is a good reason not
to do x, that x is not a non-RC bug in your package.
This is the key difference between how policy uses those terms and RFC
2119.

So, I think Russ is correct that what we're saying is that you should do
x unless there is an adequate reason not to.
If recommended in policy language actually meant that, we could say dh
is recommended, spend a bit of text giving examples of reasons why it
doesn't apply and be done.

I'd be in favor of changing policy so that should meant should x unless
there is a good reason not to do x, but that is a much much bigger
change.

Bug#761219: debian-policy: document versioned Provides

[Sean Whitton]

Hello,

On Fri 07 Jun 2019 at 10:50AM +01, Dominic Hargreaves wrote:

> diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
> index 1d790e8..3b68420 100644
> --- a/policy/ch-relationships.rst
> +++ b/policy/ch-relationships.rst
> @@ -17,15 +17,16 @@ package names, separated by vertical bar (pipe) symbols 
> ``|``. In such a
>  case, that part of the dependency can be satisfied by any one of the
>  alternative packages.  [#]_
>
> -All of the fields except for ``Provides`` may restrict their
> -applicability to particular versions of each named package. This is done
> -in parentheses after each individual package name; the parentheses
> -should contain a relation from the list below followed by a version
> -number, in the format described in :ref:`s-f-Version`.
> +All of the fields may restrict their applicability to particular versions
> +of each named package. This is done in parentheses after each individual
> +package name; the parentheses should contain a relation from the list
> +below followed by a version number, in the format described in
> +:ref:`s-f-Version`.
>
>  The relations allowed are ``<<``, ``<=``, ``=``, ``>=`` and ``>>`` for
>  strictly earlier, earlier or equal, exactly equal, later or equal and
> -strictly later, respectively.  [#]_
> +strictly later, respectively. The exception is the Provides field, for
> +which only ``=`` is allowed.  [#]_
>
>  Whitespace may appear at any point in the version specification subject
>  to the rules in :ref:`s-controlsyntax`, and must appear
> @@ -446,17 +447,43 @@ they can say:
>  and the ``bar-plus`` package will now also satisfy the dependency for
>  the ``foo`` package.
>
> -If a relationship field has a version number attached, only real
> -packages will be considered to see whether the relationship is satisfied
> -(or the prohibition violated, for a conflict or breakage). In other
> -words, if a version number is specified, this is a request to ignore all
> -``Provides`` for that package name and consider only real packages. The
> -package manager will assume that a package providing that virtual
> -package is not of the "right" version. A ``Provides`` field may not
> -contain version numbers, and the version number of the concrete package
> -which provides a particular virtual package will not be considered when
> -considering a dependency on or conflict with the virtual package name.
> -[#]_
> +A ``Provides`` field may contain version numbers, and such a version number
> +will be considered when considering a dependency on or conflict with the
> +virtual package name.  [#]_ For example, given the following packages:
> +
> +::
> +
> +Package: foo
> +Depends: bar (>= 1.0)
> +
> +Package: bar
> +Version: 0.9
> +
> +Package: bar-plus
> +Provides: bar (= 1.0)
> +
> +the ``bar-plus`` package will again satisfy the dependency for
> +the ``foo`` package with the virtual package name.  [#]_ If the ``Provides``
> +field does not specify a version number, it will not satisfy versioned
> +dependencies or violate versioned ``Conflicts`` or ``Breaks``. For example,
> +given the following packages:
> +
> +::
> +
> +Package: foo
> +Depends: bar (>= 1.0)
> +
> +Package: bar
> +Version: 0.9
> +
> +Package: bar-plus
> +Provides: bar (= 1.0)
> +
> +Package: bar-clone
> +Provides: bar
> +
> +the ``bar-plus`` package will satisfy the dependency for the ``foo``
> +package, but the ``bar-clone`` package will not.
>
>  To specify which of a set of real packages should be the default to
>  satisfy a particular dependency on a virtual package, list the real
> @@ -670,10 +697,8 @@ dependencies.
> together and then configured in their dependency order.
>
>  .. [#]
> -   It is possible that a future release of ``dpkg`` may add the ability
> -   to specify a version number for each virtual package it provides.
> -   This feature is not yet present, however, and is expected to be used
> -   only infrequently.
> +   This functionality was introduced in dpkg 1.17.11 and newer and
> +   full support has been provided in the Debian archive since 2018.
>
>  .. [#]
> To see why ``Breaks`` is normally needed in addition to ``Replaces``,

Seconded.  Thank you again.

I've made some editorial changes (and fixed the introduction of a
duplicate footnote reference) on branch bug761219-spwhitton of
policy.git, but these do not need seconding.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#930666: Please document consensus on use of dh sequencer

[Sean Whitton]

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  ...`` or
> +``./debian/rules  ...`` 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 "" for "",
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