Debian Bug report logs - #582109
debian-policy: document triggers where appropriate

version graph

Package: debian-policy; Maintainer for debian-policy is Debian Policy List <debian-policy@lists.debian.org>; Source for debian-policy is src:debian-policy.

Reported by: Raphaël Hertzog <hertzog@debian.org>

Date: Tue, 18 May 2010 12:54:01 UTC

Severity: normal

Tags: patch

Found in version debian-policy/3.8.4.0

Reply or subscribe to this bug.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Tue, 18 May 2010 12:54:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphaël Hertzog <hertzog@debian.org>:
New Bug report received and forwarded. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Tue, 18 May 2010 12:54:05 GMT) Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Raphaël Hertzog <hertzog@debian.org>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: debian-policy: document triggers where appropriate
Date: Tue, 18 May 2010 14:50:02 +0200
Package: debian-policy
Version: 3.8.4.0
Severity: normal

The policy needs to be updated to take into account the dpkg triggers. At
the very least it needs to document the new invocations of the postinst in
chapter 6 (postinst triggered ...) see
/usr/share/doc/dpkg-dev/triggers.txt.gz

-- System Information:
Debian Release: squeeze/sid
  APT prefers unstable
  APT policy: (500, 'unstable'), (500, 'testing'), (500, 'stable'), (150, 'experimental')
Architecture: i386 (x86_64)

Kernel: Linux 2.6.32-5-amd64 (SMP w/2 CPU cores)
Locale: LANG=fr_FR.UTF-8, LC_CTYPE=fr_FR.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

debian-policy depends on no packages.

debian-policy recommends no packages.

Versions of packages debian-policy suggests:
ii  doc-base                      0.9.5      utilities to manage online documen

-- no debconf information




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Tue, 18 May 2010 17:18:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to sean finney <seanius@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Tue, 18 May 2010 17:18:04 GMT) Full text and rfc822 format available.

Message #10 received at submit@bugs.debian.org (full text, mbox):

From: sean finney <seanius@debian.org>
To: Raphaël Hertzog <hertzog@debian.org>, 582109@bugs.debian.org
Cc: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Tue, 18 May 2010 19:14:58 +0200
[Message part 1 (text/plain, inline)]
On Tue, May 18, 2010 at 02:50:02PM +0200, Raphaël Hertzog wrote:
> Package: debian-policy
> Version: 3.8.4.0
> Severity: normal
> 
> The policy needs to be updated to take into account the dpkg triggers. At
> the very least it needs to document the new invocations of the postinst in
> chapter 6 (postinst triggered ...) see
> /usr/share/doc/dpkg-dev/triggers.txt.gz

and for those who want a slightly less dense description, i wrote something
up a while back that you can feel free to borrow from:

	http://www.seanius.net/blog/2009/09/dpkg-triggers-howto/

(though i am not volunteering to do the policy writing myself)

	sean
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Tue, 18 May 2010 17:18:06 GMT) Full text and rfc822 format available.

Acknowledgement sent to sean finney <seanius@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Tue, 18 May 2010 17:18:06 GMT) Full text and rfc822 format available.

Added blocking bug(s) of 582109: 504880 Request was from Russ Allbery <rra@debian.org> to control@bugs.debian.org. (Wed, 18 Aug 2010 19:48:02 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sun, 24 Feb 2013 07:45:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 24 Feb 2013 07:45:03 GMT) Full text and rfc822 format available.

Message #22 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sun, 24 Feb 2013 16:41:55 +0900
Le Tue, May 18, 2010 at 02:50:02PM +0200, Raphaël Hertzog a écrit :
> 
> The policy needs to be updated to take into account the dpkg triggers. At
> the very least it needs to document the new invocations of the postinst in
> chapter 6 (postinst triggered ...) see
> /usr/share/doc/dpkg-dev/triggers.txt.gz

Dear all,

I am having a look at how to document triggers.  In order to simplify the
explanation and re-use more easily material from the file above, I think
that we would benefit from documenting the dpkg states for a package.

The manual page of dpkg-query indicates:

 - Not-installed
 - Config-files
 - Half-installed
 - Unpacked
 - Half-configured
 - Triggers-awaiting
 - Triggers-pending
 - Installed

The documentation in /usr/share/doc/dpkg-dev/triggers.txt.gz also
mentions config-failed.  I will look for a comprehensive list but
if you already have the answer one please let me know.

I wonder where to add this information: either in chapter 3 (binary packages)
or chapter 6 (Package maintainer scripts and installation procedure).

What do you think ?

Have a nice Sunday,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sat, 02 Mar 2013 09:48:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 02 Mar 2013 09:48:03 GMT) Full text and rfc822 format available.

Message #27 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sat, 2 Mar 2013 18:45:30 +0900
Le Sun, Feb 24, 2013 at 04:41:55PM +0900, Charles Plessy a écrit :
> 
> I am having a look at how to document triggers.  In order to simplify the
> explanation and re-use more easily material from the file above, I think
> that we would benefit from documenting the dpkg states for a package.

How about adding the following to the Policy's section 6.1 (Introduction to
package maintainer scripts) ?

          Dpkg defines the folowing states for the packages.
          <taglist>
            <tag><tt>not-installed</tt></tag>
            <item>
              The package is not installed or has been purged.
            </item>

            <tag><tt>config-files</tt></tag>
            <item>
              The package has been removed; its configuration files remain.
            </item>

            <tag><tt>half-installed</tt></tag>
            <item>
              Errors happened during installation, upgrade or removal.  Solving
              them requires the package to be re-installed.
            </item>

            <tag><tt>unpacked</tt></tag>
            <item>
              The files contained in the package have been successfuly unpacked, 
               but the maintainer scripts have not been executed.  Thus, the 
               files created by the maintainer scripts are not yet available.
            </item>

            <tag><tt>half-configured</tt></tag>
            <item>
              The package has been unpacked, and an error occured during the
              execution of one of its maintainer scripts.
            </item>

            <tag><tt>triggers-awaited</tt></tag>
            <item>
              The package has been unpacked and configured, and its
              installation activated some <prgn>dpkg</prgn> triggers that have
              not yet been executed.
            </item>

            <tag><tt>triggers-pending</tt></tag>
            <item>
              Some triggers handled by this package have been activated and are
              not yet executed.
            </item>

            <tag><tt>installed</tt></tag>
            <item>
              The package is installed, no further action is required.
            </item>
          </taglist>

For the half-installed and half-configured, I am not very confident on what I
wrote and surely feedback.

Have a nice week-end,

-- 
Charles



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sat, 02 Mar 2013 13:51:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 02 Mar 2013 13:51:03 GMT) Full text and rfc822 format available.

Message #32 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sat, 2 Mar 2013 22:49:59 +0900
[Message part 1 (text/plain, inline)]
Dear all,

pasting a lot from /usr/share/doc/dpkg-dev/triggers.txt.gz and deb-triggers(1),
I have drafted a patch to the Policy to document triggers.

Your comments are very welcome.

Have a nice week-end,

-- 
Charles
[0001-Document-dpkg-triggers.patch (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sat, 02 Mar 2013 14:39:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Guillem Jover <guillem@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 02 Mar 2013 14:39:03 GMT) Full text and rfc822 format available.

Message #37 received at 582109@bugs.debian.org (full text, mbox):

From: Guillem Jover <guillem@debian.org>
To: Charles Plessy <plessy@debian.org>, 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sat, 2 Mar 2013 15:37:36 +0100
Hi!

On Sat, 2013-03-02 at 18:45:30 +0900, Charles Plessy wrote:
> Le Sun, Feb 24, 2013 at 04:41:55PM +0900, Charles Plessy a écrit :
> > I am having a look at how to document triggers.  In order to simplify the
> > explanation and re-use more easily material from the file above, I think
> > that we would benefit from documenting the dpkg states for a package.

This is documented in the dpkg man page (PACKAGE STATES), sorry for
not mentioning this before.

> How about adding the following to the Policy's section 6.1 (Introduction to
> package maintainer scripts) ?

We unified the states in policy to be all capitalized some time ago,
I think it would make sense to follow that convention to not confuse
the terminology usage.

>           Dpkg defines the folowing states for the packages.
>           <taglist>
>             <tag><tt>not-installed</tt></tag>
>             <item>
>               The package is not installed or has been purged.
>             </item>

I'm not sure, if we should mention how to transition from/to states in
this description, doing that in a dedicated section on how those
transitions happen might be better (this re to the “has been purged”).

>             <tag><tt>config-files</tt></tag>
>             <item>
>               The package has been removed; its configuration files remain.
>             </item>

Related to state transitions, I'd talk about the current state (is) not
how we got there (has been), here and in all other state descriptions.

>             <tag><tt>half-installed</tt></tag>
>             <item>
>               Errors happened during installation, upgrade or removal.  Solving
>               them requires the package to be re-installed.
>             </item>

... or removed. Same comment about state transitions.

>             <tag><tt>unpacked</tt></tag>
>             <item>
>               The files contained in the package have been successfuly unpacked, 
>                but the maintainer scripts have not been executed.  Thus, the 
>                files created by the maintainer scripts are not yet available.
>             </item>

Configuration might involve changing existing files, or changing
parameters through existing APIs that change, say, a database on the
backend for example, so I'd avoid explicitly mentioning that files
might not be available, as that's not really comprehensive.

>             <tag><tt>half-configured</tt></tag>
>             <item>
>               The package has been unpacked, and an error occured during the
>               execution of one of its maintainer scripts.
>             </item>

Same comment about state transitions. This state could also happen during
removal for example.

>             <tag><tt>triggers-awaited</tt></tag>
>             <item>
>               The package has been unpacked and configured, and its
>               installation activated some <prgn>dpkg</prgn> triggers that have
>               not yet been executed.
>             </item>

I'd say that the triggers need to be processed, and not executed. Also
do we need to say that those are dpkg triggers, I'd say they are just
package triggers.

>             <tag><tt>triggers-pending</tt></tag>
>             <item>
>               Some triggers handled by this package have been activated and are
>               not yet executed.
>             </item>

Same comment about executed → processed.

>             <tag><tt>installed</tt></tag>
>             <item>
>               The package is installed, no further action is required.
>             </item>
>           </taglist>

The “no further action is required” seems a bit confusing, to me it
reads as there's nothing else to be done to the package ever again,
not even upgrades or removals. :)

Hope that helps.

Thanks,
Guillem



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Fri, 08 Mar 2013 00:48:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 08 Mar 2013 00:48:03 GMT) Full text and rfc822 format available.

Message #42 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Fri, 8 Mar 2013 09:44:36 +0900
[Message part 1 (text/plain, inline)]
Hi Guillem,

thank you for your comments (some quoted below).

Le Sat, Mar 02, 2013 at 03:37:36PM +0100, Guillem Jover a écrit :
> 
> This is documented in the dpkg man page (PACKAGE STATES), sorry for
> not mentioning this before.
 
> We unified the states in policy to be all capitalized some time ago,
> I think it would make sense to follow that convention to not confuse
> the terminology usage.
 
> I'm not sure, if we should mention how to transition from/to states in
> this description, doing that in a dedicated section on how those
> transitions happen might be better (this re to the “has been purged”).

To simplify things as suggested, I pasted the text from dpkg's manual page
(only changing "your system" to "the system", and removed "OK".) to the
proposed addition to the Policy.

I also corrected capitalisation.  Can you do the same in the manual pages ?
For the markup of the state names, while I am not completely satisfied with
having them flanked with quotes instead of either italics or monospaced, I
think that we can defer this to the next major release of the Policy.

I attached an updated  patch.

Have a nice day,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan
[0001-Document-dpkg-triggers.patch (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Thu, 14 Mar 2013 23:39:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Thu, 14 Mar 2013 23:39:03 GMT) Full text and rfc822 format available.

Message #47 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Fri, 15 Mar 2013 08:37:25 +0900
[Message part 1 (text/plain, inline)]
Hello everybody,

I am still seeking comments for the attached patch, that describes Dpkg
triggers.

Have a nice day,

-- 
Charles
[0001-Document-dpkg-triggers.patch (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Thu, 21 Mar 2013 23:51:12 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Thu, 21 Mar 2013 23:51:12 GMT) Full text and rfc822 format available.

Message #52 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Fri, 22 Mar 2013 08:48:40 +0900
Le Fri, Mar 15, 2013 at 04:11:19AM +0100, Guillem Jover a écrit :
> On Fri, 2013-03-15 at 08:37:25 +0900, Charles Plessy wrote:
> > I am still seeking comments for the attached patch, that describes Dpkg
> > triggers.
> 
> I've not yet allocated a chunk of time to take a look into this, will
> try to do soonish, although I don't think there's any kind of hurry
> with this for now.

Thanks Guillem,

like the other enhancements to the Policy, there is nothing that is strictly
urgent.  However, I worked with passion on this patch, and I would be very
pleased if others could also have a look at it.

In particular, for others who would think that it is be better for such a
technical patch that the final seconding comes from people who know dpkg very
well, I agree, but please do not hesitate to make comments if you see defects,
unclear or missing parts, possible improvements, etc.

Have a nice day,

-- 
Charles Plessy
Debian Med packaging team,
http://www.debian.org/devel/debian-med
Tsurumi, Kanagawa, Japan



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Wed, 10 Apr 2013 10:09:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 10 Apr 2013 10:09:04 GMT) Full text and rfc822 format available.

Message #57 received at 582109@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Charles Plessy <plessy@debian.org>
Cc: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Wed, 10 Apr 2013 12:07:19 +0200
Hi Charles,

On Fri, 15 Mar 2013, Charles Plessy wrote:
> I am still seeking comments for the attached patch, that describes Dpkg
> triggers.

Here are my comments. There's quite a bit of work left.

> >From 6a7fd0e49cb8dbd025771feb95c2dcafb408c1b8 Mon Sep 17 00:00:00 2001
> From: Charles Plessy <plessy@debian.org>
> Date: Sat, 2 Mar 2013 22:48:04 +0900
> Subject: [PATCH] Document dpkg triggers.
> 
> Closes: #582109.
> ---
>  policy.sgml | 275 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 268 insertions(+), 7 deletions(-)
> 
> diff --git a/policy.sgml b/policy.sgml
> index a41bc1f..c6e1a9e 100644
> --- a/policy.sgml
> +++ b/policy.sgml
> @@ -900,9 +900,12 @@ zope.
>  	the package.  Other control information files include
>  	the <qref id="sharedlibs-symbols"><file>symbols</file> file</qref>
>  	or <qref id="sharedlibs-shlibdeps"><file>shlibs</file> file</qref>
> -	used to store shared library dependency information and
> +	used to store shared library dependency information,
>  	the <file>conffiles</file> file that lists the package's
> -	configuration files (described in <ref id="config-files">).
> +	configuration files (described in <ref id="config-files">), and the
> +	file <file>triggers</file> that lists the

"the <file>triggers</file> file"
(invert two words)

> +	<qref id="dpkg-triggers">triggers</qref> that the package is interested
> +	in.

the triggers file (see man deb-triggers) can contain "interest" directives
but also "activate" ones. So this needs to be reworded.

For example “the triggers file wich defines the package's interaction with
dpkg's trigger system”

> +	  Dpkg defines the folowing states for the packages.
> +	  <taglist>
> +	    <tag>Not-Installed</tag>

I would use the precise states listed in dpkg(1), i.e. entirely in
lowercase. (same for all the states)

> @@ -4141,6 +4189,26 @@ Checksums-Sha256:
>  	      from the package dependencies are not available is often the
>  	      best approach.
>  	    </item>
> +
> +	    <tag><var>postinst</var> <tt>triggered</tt>
> +	      "<var>trigger-name</var> <var>trigger-name</var> ..."</tag>
> +	    <item>
> +	      Process one or more <qref id="dpkg-triggers">triggers</qref> that
> +	      this package is <em>interested</em> in.  In case of failure the
> +	      package's state becomes <tt>config-failed</tt>, so that the trigger
> +	      processing will not be attempted again until explicitly
> +	      requested<footnote>

I don't think that it's marked "config-failed" to not retry the trigger
processing. It's just that we need an error state and that config-failed
can be reused for this purpose precisely because anything done by trigger
processing is supposed to also be done during normal configuration (so it
is effectively retried on next configure).

“In case of failure the package's state becomes <tt>config-failed</tt>,
and the task associated to the trigger processing will be completed by
the <tt>postinst configure</tt> during the next package's configuration.”

> +		When an interested package has more than one trigger and wants
> +		to process them differently, the list of triggers can be can be

s/can be can be/can be/

> @@ -4694,6 +4762,198 @@ fi
>  
>  	</p>
>        </sect>
> +
> +      <sect id="dpkg-triggers">
> +	<heading>Dpkg triggers</heading>
> +
> +	<p>
> +	  A <prgn>dpkg</prgn> trigger is a facility that allows events caused
> +	  by the installation, upgrade or removal of one package, and of
> +	  <em>interest</em> to another package, to be recorded and
> +	  aggregated, and processed later by the interested package.  This
> +	  feature simplifies various registration and system-update tasks and
> +	  reduces duplication of processing.
> +	<p>

“<prgn>dpkg</prgn> triggers allows packages to monitor events caused by
the installation, upgrade or removal of packages. Monitoring packages are
said to be <em>interested</em> in some triggers. On the other side,
triggers must be <em>activated</em> to record the event notification on
the <em>interested package</em>. The latter is then said to have
<em>pending triggers</em> and the <em>activating</em> package (if any) is
said to await the processing of the trigger.

Thanks to this feature, it's easy to avoid duplication of processing logic
among packages by implementing it in one package and making sure that all
other packages rely on triggers to execute the wanted code.”

> +	<p>
> +	  Each trigger is named, and at any time zero or more packages may be
> +	  <em>interested</em> in it.  Packages declare their interest by
> +	  including a <file>triggers</file> file in their control archive.

The triggers file can contain "activate" directives too so I'd suggest
to be more explicit:

“For a package to declare its interest in a trigger, it must include one of
the <tt>interest</tt> directives in the <file>triggers</file> file in its
control archive.”

Then start a new paragraph describing the syntax of the triggers
file.

> +          This file contains one directive per line. Leading and trailing

Useless leading whitespaces on this line.

> +	  whitespace, everything after the first hash character (<tt>#</tt>)

whitespaces ? (with "s")

> +	  on any line, and empty lines are ignored.  The following directives
> +	  are supported.
> +	  <taglist>
> +	    <tag><tt>interest</tt> <var>trigger-name</var></tag>
> +	    <tag><tt>interest-noawait</tt> <var>trigger-name</var></tag>
> +	    <item>
> +	      Specifies that the package is interested in the named trigger.
> +	      The <em>noawait</em> variant does not put the triggering packages
> +	      in "Triggers-Awaited" state, and does not add the
> +	      interested package to the <tt>Triggers-Awaited</tt> list of the
> +	      triggering package.
> +	    </item>
> +
> +	    <tag><tt>activate</tt> <var>trigger-name</var></tag>
> +	    <tag><tt>activate-noawait</tt> <var>trigger-name</var></tag>
> +	    <item>
> +	      Specifies that changes to this package's state will activate the
> +	      named trigger.  The <em>noawait</em> variant does not put the
> +	      triggering packages in "Triggers-Awaited" state, and does
> +	      not add the interested package to the <tt>Triggers-Awaited</tt>
> +	      list of the triggering package.
> +	    </item>
> +	  </taglist>
> +	</p>

I'm not sure that you need to explain each time that the interested
package doesn't get added to the Triggers-Awaited field. This is just
an implementation detail of the triggers-awaited state. When we put
something in triggers-awaited, we must remember which package
needs to have its triggers processed. And we already explain it later.

> +	<p>
> +	  There currently two kinds of triggers.

+are

> +	<taglist>
> +	  <tag>Explicit triggers</tag>
> +	  <item>
> +	    These can be activated by any program by running
> +	    <prgn>dpkg-trigger</prgn> (at any time, but ideally from a
> +	    maintainer script.

missing parenthesis ")".

And you must indicate that explicit triggers can also be activated by
state changes of packages having an "activate" directive in their
triggers control file.

> +	  </item>
> +
> +	  <tag>File triggers</tag>
> +	  <item>
> +	    These are activated automatically by <prgn>dpkg</prgn> when a
> +	    matching file or directory is created, upgraded or deleted as
> +	    part of a package's unpacking or removal.  They may also be
> +	    explicitly activated by running <prgn>dpkg-trigger</prgn>.
> +	    Trigger activation due to a particular file should not generally
> +	    modify that file again.  If there are directory symlinks which
> +	    result in packages referring to files by different names, then to
> +	    be sure of activation all of the paths which might be included in
> +	    packages should be listed.  The path specified by the interested
> +	    package is matched against the path included in the triggering
> +	    package, not against the true name of the file as installed.
> +	    Only textually identical filenames (or filenames where the
> +	    interest is a directory prefix of the installed file) are
> +	    guaranteed to match.
> +	  </item>

This whole paragraph about symlinks is not at its place here. Or if you
want to keep it here, put it in a footnote so that it doesn't distract the
high level overview that this section is about.

> +	<p>
> +	  Trigger names are composed of US-ASCII characters excluding
> +	  control characters and space (i.e., characters in the range 33-126,
> +	  inclusive).  The names of file triggers is an absolute path to

The name of a file trigger is...

> +	  a file or a directory.  The names of Explicit triggers have the same
> +	  syntax as package names, but should not by identical to a package

s/by/be/

> +	<p>
> +	  When a configured package activates a trigger, its state becomes
> +	  "Triggers-Awaited" instead of "Installed".  For this
> +	  package, <prgn>dpkg</prgn> keeps a list, <tt>Triggers-Awaited</tt>
> +	  of interested packages whose trigger processing is awaited.  Every

…keeps a list of interested packages whose trigger processing is awaited
in the <tt>Triggers-Awaited</tt> field.

> +	  package in this list either has a nonempty list of pending triggers,
> +	  or is in <tt>config-failed</tt> or worse.  When a package in the
> +	  state "Triggers-Pending" becomes "Installed",
> +	  "Config-Files" or "Not-Installed", its entry is
> +	  removed from the <tt>Triggers-Awaited</tt> lists of other packages.
> +	</p>
> +
> +	<p>
> +	  When a trigger is activated, the state of every interested package
> +	  becomes "Triggers-Pending".  For each package,
> +	  <prgn>dpkg</prgn> keeps a list, <tt>Triggers-Pending</tt>, of
> +	  triggers whose processing is pending.

…keeps a list of triggers whose processing is pending in the
<tt>Triggers-Pending</tt> field.

Also you mix states written as <tt>config-failed</tt> with states
written as "Triggers-Pending". I suggest you standardize on the former.

> +	<p>
> +	  Triggers are processed by running the intersted packages'

interested

> +	  <tt>postinst</tt> script with the <tt>triggered</tt> parameter (see
> +	  <ref id="mscriptsinstact">).  This will be attempted for each
> +	  relevant package at the end of each <prgn>dpkg</prgn> run; so,

I would add "(unless --no-triggers has been used).".

> +	  normally, in the same dpkg run as the event which made the package go
> +	  to <prgn>triggers-pending</prgn>.

s/made the package go to/marked the package as/

> +	  If the package is not in state "Installed",
> +	  "Triggers-Pending" or "Triggers-Awaited" then pending
> +	  triggers are not accumulated.  However, if such a package (between
> +	  "Half-Installed" and <tt>config-failed</tt> inclusive)	
> +	  declares some trigger interests then the triggering packages will
> +	  await their configuration (which implies completion of any necessary
> +	  trigger processing) or removal.
> +	</p>
> +      </sect>

This whole section is made of many paragraphs grabbed from
various parts of /usr/share/doc/dpkg-dev/triggers.txt.gz and
really lacks a bit of structure. You should try to add some sub-sections
and group stuff by topics.

> @@ -4716,8 +4976,8 @@ fi
>            dependencies on other packages, the package names listed may
>            also include lists of alternative package names, separated
>            by vertical bar (pipe) symbols <tt>|</tt>.  In such a case,
> -          if any one of the alternative packages is installed, that
> -          part of the dependency is considered to be satisfied.
> +          if any one of the alternative packages is installed or has pending
> +	  triggers, that part of the dependency is considered to be satisfied.

“or is in <tt>triggers-pending</tt> state,”, no ?

> @@ -4978,7 +5238,8 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
>  		<prgn>postinst</prgn> or <prgn>prerm</prgn> scripts
>  		require the depended-on package to be unpacked or
>  		configured in order to run.  In the case of <tt>postinst
> -		configure</tt>, the depended-on packages will be unpacked
> +		configure</tt> and <tt>postinst triggers</tt>,

s/postinst triggers/postinst triggered/

> +	        the depended-on packages will be unpacked
>  		and configured first.  (If both packages are involved in a
>  		dependency loop, this might not work as expected; see the
>  		explanation a few paragraphs back.)  In the case
> @@ -8097,8 +8358,8 @@ Reloading <var>description</var> configuration...done.
>  	<p>
>  	  The <package>mime-support</package> package provides the
>  	  <prgn>update-mime</prgn> program, which integrates these
> -	  registrations in the <file>/etc/mailcap</file> file, using dpkg
> -	  triggers<footnote>
> +	  registrations in the <file>/etc/mailcap</file> file, using
> +	  <qref id="dpkg-triggers">dpkg triggers</qref><footnote>
>  	    Creating, modifying or removing a file in
>  	    <file>/usr/lib/mime/packages/</file> using maintainer scripts will
>  	    not activate the trigger.  In that case, it can be done by calling

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Get the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Wed, 10 Apr 2013 17:48:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 10 Apr 2013 17:48:04 GMT) Full text and rfc822 format available.

Message #62 received at 582109@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Wed, 10 Apr 2013 10:44:32 -0700
Raphael Hertzog <hertzog@debian.org> writes:
> On Fri, 15 Mar 2013, Charles Plessy wrote:

>> +	  Dpkg defines the folowing states for the packages.
>> +	  <taglist>
>> +	    <tag>Not-Installed</tag>

> I would use the precise states listed in dpkg(1), i.e. entirely in
> lowercase. (same for all the states)

I thought Guillem requested we use the capitalized versions.  I think the
capitalized versions stand out more and make it clearer that the expected
meaning isn't necessarily the plain English meaning of the phrase.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Wed, 10 Apr 2013 18:51:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 10 Apr 2013 18:51:05 GMT) Full text and rfc822 format available.

Message #67 received at 582109@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Russ Allbery <rra@debian.org>
Cc: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Wed, 10 Apr 2013 20:47:07 +0200
On Wed, 10 Apr 2013, Russ Allbery wrote:
> Raphael Hertzog <hertzog@debian.org> writes:
> > On Fri, 15 Mar 2013, Charles Plessy wrote:
> 
> >> +	  Dpkg defines the folowing states for the packages.
> >> +	  <taglist>
> >> +	    <tag>Not-Installed</tag>
> 
> > I would use the precise states listed in dpkg(1), i.e. entirely in
> > lowercase. (same for all the states)
> 
> I thought Guillem requested we use the capitalized versions.  I think the
> capitalized versions stand out more and make it clearer that the expected
> meaning isn't necessarily the plain English meaning of the phrase.

Ok, but then we ought to be consistent and avoid usage of
<tt>config-files</tt> or <tt>config-failed</tt> and other similar mention
of states elsewhere.

BTW, I just notice that <tt>config-failed</tt> in the text was wrong and
should refer to "Half-Configured".

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Get the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Wed, 10 Apr 2013 19:03:08 GMT) Full text and rfc822 format available.

Acknowledgement sent to Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 10 Apr 2013 19:03:08 GMT) Full text and rfc822 format available.

Message #72 received at 582109@bugs.debian.org (full text, mbox):

From: Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>
To: Russ Allbery <rra@debian.org>, 582109@bugs.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Wed, 10 Apr 2013 20:58:54 +0200
> On Fri, 15 Mar 2013, Charles Plessy wrote:

>> +	  Dpkg defines the folowing states for the packages.
>> +	  <taglist>
>> +	    <tag>Not-Installed</tag>

s/folowing/following

Cheers,
-- 
Bill. <ballombe@debian.org>

Imagine a large red swirl here. 



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sat, 11 May 2013 10:03:14 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 11 May 2013 10:03:14 GMT) Full text and rfc822 format available.

Message #77 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sat, 11 May 2013 19:02:41 +0900
[Message part 1 (text/plain, inline)]
Le Wed, Apr 10, 2013 at 12:07:19PM +0200, Raphael Hertzog a écrit :
> 
> Here are my comments. There's quite a bit of work left.

Thanks a lot Raphaël and everybody !

I think that I took care of all of your comments.

Here is an updated patch.  Among the changes, it introduces
sub-section to make the information easier to digest.

Cheers,

-- 
Charles
[policy-triggers.diff (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sat, 11 May 2013 13:12:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 11 May 2013 13:12:04 GMT) Full text and rfc822 format available.

Message #82 received at 582109@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Charles Plessy <plessy@debian.org>
Cc: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sat, 11 May 2013 15:09:25 +0200
Hi Charles,

On Sat, 11 May 2013, Charles Plessy wrote:
> I think that I took care of all of your comments.
> 
> Here is an updated patch.  Among the changes, it introduces
> sub-section to make the information easier to digest.

Thank you for the work! I have a few fixes and suggestions but otherwise
it looks mostly ready.

So seconded with the few suggestions below.

> +	  <p>
> +	    The <file>triggers</file> control file contains one directive per
> +	    line.  Leading and trailing whitespace, everything after the first
> +	    hash character (<tt>#</tt>) on any line, and empty lines are ignored.
> +	    The following directives are supported.
> +	    <taglist>
> +	      <tag><tt>interest</tt> <var>trigger-name</var></tag>
> +	      <tag><tt>interest-noawait</tt> <var>trigger-name</var></tag>
> +	      <item>
> +		Specifies that the package is interested in the named trigger.
> +		The <tt>interest-noawait</tt> variant does not put the
> +		triggering packages in the "Triggers-Awaited" state.
> +	      </item>
> +
> +	      <tag><tt>activate</tt> <var>trigger-name</var></tag>
> +	      <tag><tt>activate-noawait</tt> <var>trigger-name</var></tag>
> +	      <item>
> +		Specifies that changes to this package's state will activate the
> +		named trigger.  The <tt>activate-noawait</tt> variant does not
> +		put this package in the "Triggers-Awaited" state.
> +	      </item>
> +	    </taglist>
> +	  </p>

Here I would add a small paragraph recommending the usage of the -noawait
variants unless they are strictly required.

<p>The <tt>*-noawait</tt> directives should be used by default to avoid
putting packages in the "Trigger-Awaited" status. Packages should only end up
in this intermediary status when they are effectively broken until the
awaited triggers have been processed. A package in "Trigger-Awaited" does
not satisfy dependencies, for this reason an excessive and injustified amount of package
in this status can lead to early processing of triggers or even to dependency
loops.</p>

> +	  <p>
> +	    When a configured package activates a trigger, its state becomes
> +	    "Triggers-Awaited" instead of "Installed".  For this package,
> +	    <prgn>dpkg</prgn> keeps a list, <tt>Triggers-Awaited</tt> of

missing comma after "Triggers-Awaited</tt>", but I would rather rewrite it
like this:

keeps a list of interested packages whose trigger processing is awaited
(that list is stored in the <tt>Triggers-Awaited</tt> field in dpkg's status
database)

> +	    interested packages whose trigger processing is awaited.  Every
> +	    package in this list either has a nonempty list of pending
> +	    triggers, or is in "Half-Configured" or worse.  When a package in
> +	    the state "Triggers-Pending" becomes "Installed", "Config-Files" or
> +	    "Not-Installed", its entry is removed from the
> +	    <tt>Triggers-Awaited</tt> lists of other packages.
> +	  </p>
> +
> +	  <p>
> +	    When a trigger is activated, the state of every interested package
> +	    becomes "Triggers-Pending".  For each package, <prgn>dpkg</prgn>
> +	    keeps a list, <tt>Triggers-Pending</tt>, of triggers whose
> +	    processing is pending.  Repeated activation of the same trigger has

Same suggested rewrite as above here.

> +	    no additional effect.  In general a trigger will not be processed
> +	    immediately when it is activated; processing is deferred until it is
> +	    convenient.
> +	  </p>
> +
[...]
> +	    Packages in "Half-Configured" or worse never have pending triggers.
> +	    A package is only guaranteed to become notified of a trigger
> +            activation if it is continuously interested in the trigger, and never
> +            in "Half-Configured" or worse.  A package whose postinst is being run

weird spacing here

> +	    can however acquire pending triggers during that run (ie, a package
> +	    can trigger itself).
> +	  </p>
> +
> +	  <p>
> +	    However, if such a package (between "Half-Installed" and
> +	    "Half-Configured" inclusive) declares some trigger interests then the
> +	    triggering packages will await their configuration (which implies
> +	    completion of any necessary trigger processing) or removal.
> +	  </p>
> +
> +	  <p>
> +	    For this reason, the <tt>postinst</tt> scripts it must do whatever

s/it//

> +	    actions are necessary to deal with any trigger activations when they
> +	    are called with <tt>configure</tt>.
> +	  </p>
> +	</sect1>
> +      </sect>
>      </chapt>

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Get the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sun, 12 May 2013 02:48:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 12 May 2013 02:48:04 GMT) Full text and rfc822 format available.

Message #87 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sun, 12 May 2013 11:45:59 +0900
[Message part 1 (text/plain, inline)]
Hi Raphaël,

thanks for the quick feedback.

In the list of directives, I have moved the "noawait" variant on top to
better show that they are the default choice.  I also reworded your suggestion
to make it a positive recommenation: use "interest" and "activate" only
if you want to put the triggering package in "Trigger-Awaited" state.

Le Sat, May 11, 2013 at 03:09:25PM +0200, Raphael Hertzog a écrit :
> 
> > +	  <p>
> > +	    The <file>triggers</file> control file contains one directive per
> > +	    line.  Leading and trailing whitespace, everything after the first
> > +	    hash character (<tt>#</tt>) on any line, and empty lines are ignored.
> > +	    The following directives are supported.
> > +	    <taglist>
> > +	      <tag><tt>interest</tt> <var>trigger-name</var></tag>
> > +	      <tag><tt>interest-noawait</tt> <var>trigger-name</var></tag>
> > +	      <item>
> > +		Specifies that the package is interested in the named trigger.
> > +		The <tt>interest-noawait</tt> variant does not put the
> > +		triggering packages in the "Triggers-Awaited" state.
> > +	      </item>
> > +
> > +	      <tag><tt>activate</tt> <var>trigger-name</var></tag>
> > +	      <tag><tt>activate-noawait</tt> <var>trigger-name</var></tag>
> > +	      <item>
> > +		Specifies that changes to this package's state will activate the
> > +		named trigger.  The <tt>activate-noawait</tt> variant does not
> > +		put this package in the "Triggers-Awaited" state.
> > +	      </item>
> > +	    </taglist>
> > +	  </p>
> 
> Here I would add a small paragraph recommending the usage of the -noawait
> variants unless they are strictly required.
> 
> <p>The <tt>*-noawait</tt> directives should be used by default to avoid
> putting packages in the "Trigger-Awaited" status. Packages should only end up
> in this intermediary status when they are effectively broken until the
> awaited triggers have been processed. A package in "Trigger-Awaited" does
> not satisfy dependencies, for this reason an excessive and injustified amount of package
> in this status can lead to early processing of triggers or even to dependency
> loops.</p>

Here is my proposition:

        <heading>Syntax</heading>

          <p>
            The <file>triggers</file> control file contains one directive per
            line.  Leading and trailing whitespace, everything after the first
            hash character (<tt>#</tt>) on any line, and empty lines are ignored.
            The following directives are supported.
            <taglist>
              <tag><tt>interest-noawait</tt> <var>trigger-name</var></tag>
              <tag><tt>interest</tt> <var>trigger-name</var></tag>
              <item>
                Specifies that the package is interested in the named trigger.
                The <tt>interest</tt> variant puts the triggering packages in
                the "Triggers-Awaited" state, and the <tt>interest-noawait</tt>
                variant does not.
              </item>

              <tag><tt>activate-noawait</tt> <var>trigger-name</var></tag>
              <tag><tt>activate</tt> <var>trigger-name</var></tag>
              <item>
                Specifies that changes to this package's state will activate the
                named trigger.  The <tt>activate</tt> variant puts this package
                in the "Triggers-Awaited" state, and the
                <tt>activate-noawait</tt> variant does not.
              </item>
            </taglist>
          </p>

          <p>
            The <tt>*-noawait</tt> directives should be used unless the 
            packages awaiting triggers can not satisfy <tt>Depends</tt>
            relationships until the triggers have been processed.  
            In that case, the <tt>interest</tt> or <tt>activate</tt> directives
            should be used, as they will put the triggering packges in the
            "Triggers-Awaited" state, which does not satisfy dependencies.
            Note that pakcages unnecessarly entering this state can cause the
            early processing of triggers or even dependency loops.
          </p>

I also added "through the <tt>interst</tt> or <tt>activate</tt> directives"
after "When a configured package activates a trigger".

I applied the other changes you proposed as well, with minor rewording:

-           <prgn>dpkg</prgn> keeps a list, <tt>Triggers-Awaited</tt> of
-           interested packages whose trigger processing is awaited.  Every
+           <prgn>dpkg</prgn> keeps a list of interested packages whose trigger
+           processing is awaited, which is stored in the
+           <tt>Triggers-Awaited</tt> field in dpkg's status database.  Every

I attached an updated version of the patch.

Cheers,

-- 
Charles
[policy-triggers.diff (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sun, 12 May 2013 08:12:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 12 May 2013 08:12:04 GMT) Full text and rfc822 format available.

Message #92 received at 582109@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Charles Plessy <plessy@debian.org>
Cc: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sun, 12 May 2013 10:09:17 +0200
Hi,

On Sun, 12 May 2013, Charles Plessy wrote:
>           <p>
>             The <tt>*-noawait</tt> directives should be used unless the 
>             packages awaiting triggers can not satisfy <tt>Depends</tt>
>             relationships until the triggers have been processed.  
>             In that case, the <tt>interest</tt> or <tt>activate</tt> directives
>             should be used, as they will put the triggering packges in the
>             "Triggers-Awaited" state, which does not satisfy dependencies.
>             Note that pakcages unnecessarly entering this state can cause the

s/pakcages/packages/

>             early processing of triggers or even dependency loops.
>           </p>
> 
> I also added "through the <tt>interst</tt> or <tt>activate</tt> directives"
> after "When a configured package activates a trigger".
> 
> I applied the other changes you proposed as well, with minor rewording:
> 
> -           <prgn>dpkg</prgn> keeps a list, <tt>Triggers-Awaited</tt> of
> -           interested packages whose trigger processing is awaited.  Every
> +           <prgn>dpkg</prgn> keeps a list of interested packages whose trigger
> +           processing is awaited, which is stored in the
> +           <tt>Triggers-Awaited</tt> field in dpkg's status database.  Every
> 
> I attached an updated version of the patch.

Thanks, I agree that your improved wording is better. Seconded.

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Get the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Wed, 15 May 2013 23:42:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 15 May 2013 23:42:04 GMT) Full text and rfc822 format available.

Message #97 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Thu, 16 May 2013 08:38:24 +0900
Le Sun, May 12, 2013 at 10:09:17AM +0200, Raphael Hertzog a écrit :
> 
> Thanks, I agree that your improved wording is better. Seconded.

Thanks again.

Guillem recently posted on debian-devel about "noawait" triggers, and I would
like to send a link to the patch to the Policy once it gets futher
proof-reading and seconds.  Or if it takes time, shall I point to this bug log
on -devel ?

Cheers,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Thu, 16 May 2013 11:36:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Thu, 16 May 2013 11:36:04 GMT) Full text and rfc822 format available.

Message #102 received at 582109@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Charles Plessy <plessy@debian.org>
Cc: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Thu, 16 May 2013 13:32:55 +0200
Hi,

On Thu, 16 May 2013, Charles Plessy wrote:
> Guillem recently posted on debian-devel about "noawait" triggers, and I would
> like to send a link to the patch to the Policy once it gets futher
> proof-reading and seconds.  Or if it takes time, shall I point to this bug log
> on -devel ?

I don't see any harm to mentioning it right now. And maybe point Ian
Jackson to it, he might want to review and second it...

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Get the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Thu, 04 Jul 2013 02:30:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Thu, 04 Jul 2013 02:30:04 GMT) Full text and rfc822 format available.

Message #107 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Thu, 4 Jul 2013 11:26:01 +0900
Le Sun, May 12, 2013 at 10:09:17AM +0200, Raphael Hertzog a écrit :
> On Sun, 12 May 2013, Charles Plessy wrote:
> > 
> > I also added "through the <tt>interst</tt> or <tt>activate</tt> directives"
> > after "When a configured package activates a trigger".
> > 
> > I applied the other changes you proposed as well, with minor rewording:
> > 
> > -           <prgn>dpkg</prgn> keeps a list, <tt>Triggers-Awaited</tt> of
> > -           interested packages whose trigger processing is awaited.  Every
> > +           <prgn>dpkg</prgn> keeps a list of interested packages whose trigger
> > +           processing is awaited, which is stored in the
> > +           <tt>Triggers-Awaited</tt> field in dpkg's status database.  Every
> > 
> > I attached an updated version of the patch.
> 
> Thanks, I agree that your improved wording is better. Seconded.

Dear all,

now that Wheezy is released, I hope that everybody has more time to review the
patch to integrate triggers in the Policy and confirm Raphaël's seconding or
propose extra corrections or improvements.

    http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=87;filename=policy-triggers.diff;att=1;bug=582109

Have a nice day,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sun, 14 Jul 2013 12:39:09 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 14 Jul 2013 12:39:09 GMT) Full text and rfc822 format available.

Message #112 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sun, 14 Jul 2013 21:34:54 +0900
tag 582109 patch
thanks

Le Thu, Jul 04, 2013 at 11:26:01AM +0900, Charles Plessy a écrit :
> 
> now that Wheezy is released, I hope that everybody has more time to review the
> patch to integrate triggers in the Policy and confirm Raphaël's seconding or
> propose extra corrections or improvements.
> 
>     http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=87;filename=policy-triggers.diff;att=1;bug=582109

Dear all,

I would like to give a firmer call for seconds, so that we can close this issue
and move to the next big change: either multi-arch, or the conversion to
DocBook XML.

Have a nice day,

Charles

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan



Added tag(s) patch. Request was from Charles Plessy <plessy@debian.org> to control@bugs.debian.org. (Sun, 14 Jul 2013 12:39:18 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Tue, 16 Jul 2013 15:12:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Julien Cristau <jcristau@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Tue, 16 Jul 2013 15:12:04 GMT) Full text and rfc822 format available.

Message #119 received at 582109@bugs.debian.org (full text, mbox):

From: Julien Cristau <jcristau@debian.org>
To: Charles Plessy <plessy@debian.org>, 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Tue, 16 Jul 2013 17:09:08 +0200
[Message part 1 (text/plain, inline)]
On Thu, Jul  4, 2013 at 11:26:01 +0900, Charles Plessy wrote:

> Le Sun, May 12, 2013 at 10:09:17AM +0200, Raphael Hertzog a écrit :
> > On Sun, 12 May 2013, Charles Plessy wrote:
> > > 
> > > I also added "through the <tt>interst</tt> or <tt>activate</tt> directives"
> > > after "When a configured package activates a trigger".
> > > 
> > > I applied the other changes you proposed as well, with minor rewording:
> > > 
> > > -           <prgn>dpkg</prgn> keeps a list, <tt>Triggers-Awaited</tt> of
> > > -           interested packages whose trigger processing is awaited.  Every
> > > +           <prgn>dpkg</prgn> keeps a list of interested packages whose trigger
> > > +           processing is awaited, which is stored in the
> > > +           <tt>Triggers-Awaited</tt> field in dpkg's status database.  Every
> > > 
> > > I attached an updated version of the patch.
> > 
> > Thanks, I agree that your improved wording is better. Seconded.
> 
> Dear all,
> 
> now that Wheezy is released, I hope that everybody has more time to review the
> patch to integrate triggers in the Policy and confirm Raphaël's seconding or
> propose extra corrections or improvements.
> 
>     http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=87;filename=policy-triggers.diff;att=1;bug=582109
> 
That patch has a bunch of typos (I noticed a few in spelling "package").

Also it doesn't seem to warn against triggers being called with Depends
not satisfied, which caused no end of trouble for upgrades to wheezy,
and which is probably going to bite us again for jessie.

Cheers,
Julien
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Tue, 16 Jul 2013 23:36:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Tue, 16 Jul 2013 23:36:04 GMT) Full text and rfc822 format available.

Message #124 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Wed, 17 Jul 2013 08:33:45 +0900
Le Tue, Jul 16, 2013 at 05:09:08PM +0200, Julien Cristau a écrit :
> On Thu, Jul  4, 2013 at 11:26:01 +0900, Charles Plessy wrote:
> > 
> >     http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=87;filename=policy-triggers.diff;att=1;bug=582109
> > 
> That patch has a bunch of typos (I noticed a few in spelling "package").

> Also it doesn't seem to warn against triggers being called with Depends
> not satisfied, which caused no end of trouble for upgrades to wheezy,
> and which is probably going to bite us again for jessie.

Hi Julien,

thank you for your comments and sorry for forgetting to run a spellchecker.  I
will make the following spelling corrections. 

    s/wich/which/
    s/activations/activation/
    s/packges/packages/
    s/unnecessarly/unnecessarily/
    s/mechanims/mechanism/

About the problem of triggers being called with Depends not satisfied, can you
give more explanations or suggest some text for the warning ?  Would it be
enough to add a notice that the triggered postinst script may be called when
the package is "Unpacked", which is a state that does not require that the
packages that are depended on are configured ?

Also, if you think that triggers will give us problems for the Jessie release,
may I suggest that you give it a broad audience on debian-devel ?  As a
maintainer of a package that has triggers, I am definitely interested to learn
if there is something I should give particular attention there.

Have a nice day,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Wed, 17 Jul 2013 07:42:08 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 17 Jul 2013 07:42:08 GMT) Full text and rfc822 format available.

Message #129 received at 582109@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Charles Plessy <plessy@debian.org>
Cc: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Wed, 17 Jul 2013 09:27:19 +0200
Hi,

On Wed, 17 Jul 2013, Charles Plessy wrote:
> About the problem of triggers being called with Depends not satisfied, can you
> give more explanations or suggest some text for the warning ?  Would it be
> enough to add a notice that the triggered postinst script may be called when
> the package is "Unpacked", which is a state that does not require that the
> packages that are depended on are configured ?

Julien is referring to this bug:
http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=671711

It might be fixed for jessie, at least I hope so, but he seems to doubt
it.

> Also, if you think that triggers will give us problems for the Jessie release,
> may I suggest that you give it a broad audience on debian-devel ?  As a
> maintainer of a package that has triggers, I am definitely interested to learn
> if there is something I should give particular attention there.

One of the main things to do is to switch as many packages as possible to
use the interest-noawait directive when possible.

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Discover the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Wed, 17 Jul 2013 23:57:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 17 Jul 2013 23:57:04 GMT) Full text and rfc822 format available.

Message #134 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Thu, 18 Jul 2013 08:55:20 +0900
Le Wed, Jul 17, 2013 at 09:27:19AM +0200, Raphael Hertzog a écrit :
> 
> Julien is referring to this bug:
> http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=671711
> 
> It might be fixed for jessie, at least I hope so, but he seems to doubt
> it.
> 
> > Also, if you think that triggers will give us problems for the Jessie release,
> > may I suggest that you give it a broad audience on debian-devel ?  As a
> > maintainer of a package that has triggers, I am definitely interested to learn
> > if there is something I should give particular attention there.
> 
> One of the main things to do is to switch as many packages as possible to
> use the interest-noawait directive when possible.

Hi all,

regarding “noawait” triggers, the patch already contains the following, which
is new and improved compared to the existing documentation.

    The <tt>*-noawait</tt> directives should be used unless the
    packages awaiting triggers can not satisfy <tt>Depends</tt>
    relationships until the triggers have been processed.

After reading #671711 and /usr/share/doc/dpkg-dev/triggers.txt.gz, my
impression is that a package can not become "Unpacked" and keep a list of
pending triggers, because of the following statements in triggers.txt:

 1) Pending triggers are marked "never" for "Unpacked" packages in the overview
    table.

 2) The section "Details - triggered package" mentions that "packages in
    ‘config-failed’ or worse are never considered to have lists of pending
    triggers".  (Where config-failed means Half-Installed).  In my understanding of
    Dpkg states, Unpacked is "worse" than Half-Installed.

There are two consequences to this:

 - "postinst configure" should do at least everything needed by
   "postinst triggers", since in the situations where triggers are dropped,
   the package is in a state that ensures that "postinst configure" will be run.

 - we could write in section 6.5 of the Policy that for "postinst triggers"
   the requirements are the same as for "postinst abort-*":

     "The files contained in the package will be unpacked. All package
     dependencies will at least be "Half-Installed" and will have previously been
     configured and not removed. However, dependencies may not be configured or even
     fully unpacked in some error situations."

I understand that changes in dpkg can enchance the mechanism to use triggers,
thus reducing the risk of having bugs, but I think that in #671711, dpkg is
following the specification, unless it failed to clear the list of pending
triggers when monodoc-browser became unpacked when it was upgraded.

Is that correct ?  If yes, then I propose to go ahead and apply an improved
patch to the policy that mentions the restrictions and requirements on
"postinst triggers", because it represents an enhancement to the existing
documentation.

Have a nice day,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Thu, 18 Jul 2013 00:30:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Thu, 18 Jul 2013 00:30:05 GMT) Full text and rfc822 format available.

Message #139 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Thu, 18 Jul 2013 09:26:02 +0900
Le Thu, Jul 18, 2013 at 08:55:20AM +0900, Charles Plessy a écrit :
> 
> regarding “noawait” triggers, the patch already contains the following, which
> is new and improved compared to the existing documentation.
> 
>     The <tt>*-noawait</tt> directives should be used unless the
>     packages awaiting triggers can not satisfy <tt>Depends</tt>
>     relationships until the triggers have been processed.

By the way, are the “noawait” triggers guaranteed to be executed only after the
triggering package has entered the "Installed" state, or can they be executed
at the same time of other triggers as well ?

Cheers,

-- 
Charles



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Thu, 18 Jul 2013 00:51:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Thu, 18 Jul 2013 00:51:04 GMT) Full text and rfc822 format available.

Message #144 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Thu, 18 Jul 2013 09:46:29 +0900
Le Thu, Jul 18, 2013 at 08:55:20AM +0900, Charles Plessy a écrit :
> 
>  2) The section "Details - triggered package" mentions that "packages in
>     ‘config-failed’ or worse are never considered to have lists of pending
>     triggers".  (Where config-failed means Half-Installed).  In my understanding of
>     Dpkg states, Unpacked is "worse" than Half-Installed.

Sorry for the noise: I meant "Half-Configured", not "Half-Installed".

Cheers,

-- 
Charles



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Thu, 18 Jul 2013 06:54:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Thu, 18 Jul 2013 06:54:05 GMT) Full text and rfc822 format available.

Message #149 received at 582109@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Charles Plessy <plessy@debian.org>
Cc: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Thu, 18 Jul 2013 08:51:09 +0200
On Thu, 18 Jul 2013, Charles Plessy wrote:
> Le Thu, Jul 18, 2013 at 08:55:20AM +0900, Charles Plessy a écrit :
> > 
> > regarding “noawait” triggers, the patch already contains the following, which
> > is new and improved compared to the existing documentation.
> > 
> >     The <tt>*-noawait</tt> directives should be used unless the
> >     packages awaiting triggers can not satisfy <tt>Depends</tt>
> >     relationships until the triggers have been processed.
> 
> By the way, are the “noawait” triggers guaranteed to be executed only after the
> triggering package has entered the "Installed" state, or can they be executed
> at the same time of other triggers as well ?

There's no such guaranty. A package that triggers another package only
knows that the triggers will be processed at some point in the future. It
doesn't know if if will before or after its own configuration (the
"noawait" doesn't change anything here except that the trigger requirement
is not recorded).

Even with traditional triggers, it's possible that dpkg will configure a package
before processing the triggers that it awaits. What this means is just
that the end status will be "Triggers-Awaited" instead "Installed".

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Discover the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Thu, 18 Jul 2013 07:12:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Thu, 18 Jul 2013 07:12:05 GMT) Full text and rfc822 format available.

Message #154 received at 582109@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Charles Plessy <plessy@debian.org>
Cc: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Thu, 18 Jul 2013 09:00:44 +0200
Hi,

On Thu, 18 Jul 2013, Charles Plessy wrote:
> After reading #671711 and /usr/share/doc/dpkg-dev/triggers.txt.gz, my
> impression is that a package can not become "Unpacked" and keep a list of
> pending triggers, because of the following statements in triggers.txt:
> 
>  1) Pending triggers are marked "never" for "Unpacked" packages in the overview
>     table.
> 
>  2) The section "Details - triggered package" mentions that "packages in
>     ‘config-failed’ or worse are never considered to have lists of pending
>     triggers".  (Where config-failed means Half-Installed).  In my understanding of
>     Dpkg states, Unpacked is "worse" than Half-Installed.
> 
> There are two consequences to this:
> 
>  - "postinst configure" should do at least everything needed by
>    "postinst triggers", since in the situations where triggers are dropped,
>    the package is in a state that ensures that "postinst configure" will be run.

Yes, that's pretty important. I haven't checked if this was already
documented in your patch, but it definitely is a clear rule in the
/usr/share/doc/dpkg-dev/triggers.txt.gz.

>  - we could write in section 6.5 of the Policy that for "postinst triggers"
>    the requirements are the same as for "postinst abort-*":
> 
>      "The files contained in the package will be unpacked. All package
>      dependencies will at least be "Half-Installed" and will have previously been
>      configured and not removed. However, dependencies may not be configured or even
>      fully unpacked in some error situations."

Why not, but then please add a footnote explaining that this ought to be
temporary until the dpkg bug gets fixed. Because it's not really a
satisfactory situation.

> I understand that changes in dpkg can enchance the mechanism to use triggers,
> thus reducing the risk of having bugs, but I think that in #671711, dpkg is
> following the specification, unless it failed to clear the list of pending
> triggers when monodoc-browser became unpacked when it was upgraded.

The documentation says "Packages in t-awaited and t-pending demand
satisfaction of their dependencies just like packages in installed.".

This is the part that is not respected in the above bug. So no, it's not
really following the specification.

> Is that correct ?  If yes, then I propose to go ahead and apply an improved
> patch to the policy that mentions the restrictions and requirements on
> "postinst triggers", because it represents an enhancement to the existing
> documentation.

Definitely.

jessie development is live, we want to draw the attention of people to
review their triggers and do the right thing.

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Discover the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sat, 20 Jul 2013 03:36:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 20 Jul 2013 03:36:04 GMT) Full text and rfc822 format available.

Message #159 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sat, 20 Jul 2013 12:32:25 +0900
Thanks again Raphaël for your prompt feedback.

Le Thu, Jul 18, 2013 at 09:00:44AM +0200, Raphael Hertzog a écrit :
> 
> On Thu, 18 Jul 2013, Charles Plessy wrote:
> > 
> >  - "postinst configure" should do at least everything needed by
> >    "postinst triggers", since in the situations where triggers are dropped,
> >    the package is in a state that ensures that "postinst configure" will be run.
> 
> Yes, that's pretty important. I haven't checked if this was already
> documented in your patch, but it definitely is a clear rule in the
> /usr/share/doc/dpkg-dev/triggers.txt.gz.

The current patch adds the following to the paragraph describing "postinst
configure" in section 6.5.

    Even when called with <tt>configure</tt>, this script must do whatever actions
    are necessary to deal with any <qref
    id="dpkg-triggers-intermediate-states">triggers</qref> activation.

This is repeated at the end of the new section on triggers.

    For this reason, the <tt>postinst</tt> scripts must do whatever
    actions are necessary to deal with any trigger activation when they
    are called with <tt>configure</tt>.


> >  - we could write in section 6.5 of the Policy that for "postinst triggers"
> >    the requirements are the same as for "postinst abort-*":
> > 
> >      "The files contained in the package will be unpacked. All package
> >      dependencies will at least be "Half-Installed" and will have previously been
> >      configured and not removed. However, dependencies may not be configured or even
> >      fully unpacked in some error situations."
> 
> Why not, but then please add a footnote explaining that this ought to be
> temporary until the dpkg bug gets fixed. Because it's not really a
> satisfactory situation.

Can you explain what the bug is and what the correction will be ?  Because I
have the impression that the root of the problem is only that the current
documentation is misleading, and that dpkg does exactly what it is expected.
From the documentation:

    Packages in t-awaited and t-pending demand satisfaction of their
    dependencies just like packages in installed.

The misleading point is "just like packages in installed".  In my
understanding, when a package is upgraded, the packages that depend on it stay
in the "Installed" state while the new version of the upgraded package is
unpacked and configured.  Not just the triggers, but also any other command not
related to the dpkg or apt session that would happen to run at that time can
fail if they strictly require a function that is not available between unpack
and configure.

I do not see any other solution than applying the same restrictions on
"postinst triggered" as for "postinst configure".  (PS: after reading the
thread again, I just noticed that this also what you wrote in #671711#68).
(PPS: By the way, apart from Manoj's excellent diagrams at
<http://people.debian.org/~srivasta/MaintainerScripts.html#sec-3.4.3>, is there
an extensive documentation on how package upgrades are handled by APT and Dpkg ?)

In the case of #671711, I wonder if monodoc-browser is simply abusing the
triggers mechanism, since the only thing that its postint script does when
called with "configure" is to trigger itself.

Altogether, I propose to document that the requirements are the same for
"postinst triggered" as for "postinst configure", and go ahead with updating
the Policy.  In my understanding, the proposed improvements to Dpkg can reduce,
but not completely eliminate, the cases where fragile postinst scripts break
when triggered.

Have a nice week-end,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sun, 21 Jul 2013 19:39:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 21 Jul 2013 19:39:05 GMT) Full text and rfc822 format available.

Message #164 received at 582109@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Charles Plessy <plessy@debian.org>, 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sun, 21 Jul 2013 21:36:52 +0200
On Sat, 20 Jul 2013, Charles Plessy wrote:
> Can you explain what the bug is and what the correction will be ?  Because I

The bug is that triggers are run while the dependencies of the triggered
package are not satisfied. The fix is not to do that and wait until those
dependencies are satisfied (but guillem mentionned that it also needs some
cycle breaking code).

> The misleading point is "just like packages in installed".  In my
> understanding, when a package is upgraded, the packages that depend on it stay
> in the "Installed" state while the new version of the upgraded package is
> unpacked and configured.  Not just the triggers, but also any other command not
> related to the dpkg or apt session that would happen to run at that time can
> fail if they strictly require a function that is not available between unpack
> and configure.

That's true but it's not really comparable. "postinst triggered" ought to
work like "postinst configure" and there you have the guaranty that the
dependencies are configured.

> I do not see any other solution than applying the same restrictions on
> "postinst triggered" as for "postinst configure".  (PS: after reading the
> thread again, I just noticed that this also what you wrote in #671711#68).

I did not write that. On the contrary, re-read:

“The problematic fix is to ensure the same requirements for "postinst
triggered" as for "postinst configure". But we could enforce some
requirements that would probably solve the issues we saw without
introducing cycles.”

There are no "restrictions" for "postinst configure" (you can rely on
dependencies — except if you have a dependency cycle) and there should be
no restrictions for "postinst triggered". But right now, dpkg doesn't
ensure anything. And instead of nothing checked by dpkg, I suggested to
ensure some requirements nevertheless but which are less demanding than
those used by "postinst configure".

> (PPS: By the way, apart from Manoj's excellent diagrams at
> <http://people.debian.org/~srivasta/MaintainerScripts.html#sec-3.4.3>, is there
> an extensive documentation on how package upgrades are handled by APT and Dpkg ?)

I know https://wiki.debian.org/MaintainerScripts too but that's all.

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Discover the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sun, 21 Jul 2013 22:27:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 21 Jul 2013 22:27:04 GMT) Full text and rfc822 format available.

Message #169 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Mon, 22 Jul 2013 07:24:30 +0900
[Message part 1 (text/plain, inline)]
Le Sun, Jul 21, 2013 at 09:36:52PM +0200, Raphael Hertzog a écrit :
> 
> There are no "restrictions" for "postinst configure" (you can rely on
> dependencies — except if you have a dependency cycle) and there should be
> no restrictions for "postinst triggered". But right now, dpkg doesn't
> ensure anything. And instead of nothing checked by dpkg, I suggested to
> ensure some requirements nevertheless but which are less demanding than
> those used by "postinst configure".

Sorry for the poorly chosen use of the word "restrictions" here...

Nevertheless, please let me try to refocus on the question of whether
the Policy can be updated or not.

Here is what is written in the Policy about "postinst configure":

    The files contained in the package will be unpacked. All package
    dependencies will at least be unpacked.

The corollary is that there is no guarantee that the dependencies will be
configured, and my understanding of #671711 is that it currently applies to
"postinst triggered" as well.

I propose to go ahead with the following:

            <tag><var>postinst</var> <tt>triggered</tt>
              "<var>trigger-name</var> <var>trigger-name</var> ..."</tag>
            <item>
              The files contained in the package will be unpacked.  All
              package dependencies will at least be "Unpacked"<footnote>
              There is work under way on <prgn>dpkg</prgn> to ensure that
              the requirement on <tt>postinst triggered</tt> is less demanding
              than for <tt>postinst configure</tt>, see the bug number
              <url id="http://bugs.debian.org/671711" name="671711"> for
              details.</footnote>.


I attached a full version of the latest patch.

I would like to go ahead and close this bug.  If Raphaël confirms that he still
seconds the patch,  I would much appreciate if I could either have support or
actionable objection from others (preferably in the form of "unless X is done,
the patch should not be applied", rather than "it would be good to do Y").

Have a nice day,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan
[triggers-policy-2013-07-22.patch (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Mon, 22 Jul 2013 07:03:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 22 Jul 2013 07:03:05 GMT) Full text and rfc822 format available.

Message #174 received at 582109@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Charles Plessy <plessy@debian.org>
Cc: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Mon, 22 Jul 2013 09:00:59 +0200
On Mon, 22 Jul 2013, Charles Plessy wrote:
> Nevertheless, please let me try to refocus on the question of whether
> the Policy can be updated or not.

I believe we can update the policy whatever the status of this specific
bug.

> Here is what is written in the Policy about "postinst configure":
> 
>     The files contained in the package will be unpacked. All package
>     dependencies will at least be unpacked.

You're missing the important sentence that follows: “If there are no
circular dependencies involved, all package dependencies will be
configured.”

> I propose to go ahead with the following:
> 
>             <tag><var>postinst</var> <tt>triggered</tt>
>               "<var>trigger-name</var> <var>trigger-name</var> ..."</tag>
>             <item>

My suggestion:

<prgn>postinst configure</prgn> was already run and the dependencies ought
to be configured. However, dpkg currently suffers of a bug which means
that <prgn>postinst triggered</prgn> can be called while some dependencies
are being upgraded (see bug <url id="http://bugs.debian.org/671711"
name="671711">). You should thus only rely on the fact that the
dependencies are at least unpacked and were already configured once
(similar to what <tt>Pre-Depends</tt> ensures for <prgn>preinst</prgn>
maintainer scripts).

> I would like to go ahead and close this bug.  If Raphaël confirms that he still
> seconds the patch,  I would much appreciate if I could either have support or
> actionable objection from others (preferably in the form of "unless X is done,
> the patch should not be applied", rather than "it would be good to do Y").

I maintain my second provided that you fix the above.

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Discover the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Mon, 22 Jul 2013 22:51:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 22 Jul 2013 22:51:05 GMT) Full text and rfc822 format available.

Message #179 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Tue, 23 Jul 2013 07:47:32 +0900
Le Mon, Jul 22, 2013 at 09:00:59AM +0200, Raphael Hertzog a écrit :
> 
> I believe we can update the policy whatever the status of this specific
> bug.
 
> You're missing the important sentence that follows: “If there are no
> circular dependencies involved, all package dependencies will be
> configured.”

Ahem... That is embarassing.  Thanks for your patience.  Now I understand why I
did not understand.
 
> My suggestion:
> 
> <prgn>postinst configure</prgn> was already run and the dependencies ought
> to be configured. However, dpkg currently suffers of a bug which means
> that <prgn>postinst triggered</prgn> can be called while some dependencies
> are being upgraded (see bug <url id="http://bugs.debian.org/671711"
> name="671711">). You should thus only rely on the fact that the
> dependencies are at least unpacked and were already configured once
> (similar to what <tt>Pre-Depends</tt> ensures for <prgn>preinst</prgn>
> maintainer scripts).
 
> I maintain my second provided that you fix the above.

Great, and thanks for your suggestion, which I will apply.

More seconds or objections from others ?  What are the other Policy editors
thinking about this patch ?

Cheers,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Wed, 24 Jul 2013 14:03:08 GMT) Full text and rfc822 format available.

Acknowledgement sent to Julien Cristau <jcristau@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 24 Jul 2013 14:03:08 GMT) Full text and rfc822 format available.

Message #184 received at 582109@bugs.debian.org (full text, mbox):

From: Julien Cristau <jcristau@debian.org>
To: Charles Plessy <plessy@debian.org>, 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Wed, 24 Jul 2013 15:58:04 +0200
[Message part 1 (text/plain, inline)]
On Wed, Jul 17, 2013 at 09:27:19 +0200, Raphael Hertzog wrote:

> Hi,
> 
> On Wed, 17 Jul 2013, Charles Plessy wrote:
> > About the problem of triggers being called with Depends not satisfied, can you
> > give more explanations or suggest some text for the warning ?  Would it be
> > enough to add a notice that the triggered postinst script may be called when
> > the package is "Unpacked", which is a state that does not require that the
> > packages that are depended on are configured ?
> 
> Julien is referring to this bug:
> http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=671711
> 
> It might be fixed for jessie, at least I hope so, but he seems to doubt
> it.

It doesn't really matter whether it's fixed for jessie.  Since it's not
fixed in wheezy, it's relevant for packages in jessie when they're
upgraded.

Cheers,
Julien
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Wed, 24 Jul 2013 23:03:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Wed, 24 Jul 2013 23:03:05 GMT) Full text and rfc822 format available.

Message #189 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Thu, 25 Jul 2013 08:00:55 +0900
[Message part 1 (text/plain, inline)]
Le Wed, Jul 24, 2013 at 03:58:04PM +0200, Julien Cristau a écrit :
> On Wed, Jul 17, 2013 at 09:27:19 +0200, Raphael Hertzog wrote:
> 
> > On Wed, 17 Jul 2013, Charles Plessy wrote:
> > > About the problem of triggers being called with Depends not satisfied, can you
> > > give more explanations or suggest some text for the warning ?  Would it be
> > > enough to add a notice that the triggered postinst script may be called when
> > > the package is "Unpacked", which is a state that does not require that the
> > > packages that are depended on are configured ?
> > 
> > Julien is referring to this bug:
> > http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=671711
> > 
> > It might be fixed for jessie, at least I hope so, but he seems to doubt
> > it.
> 
> It doesn't really matter whether it's fixed for jessie.  Since it's not
> fixed in wheezy, it's relevant for packages in jessie when they're
> upgraded.

Hi Julien,

does the current patch (attached) address your concerns ?  If yes, would
you second it ?

The paragraph on "postinst triggers" is now as follows.

	postinst configure was already run and the dependencies ought to be configured.
	However, dpkg currently suffers of a bug which means that postinst triggered
	can be called while some dependencies are being upgraded (see bug 671711).
	Until this bug is absent from the stable release, you should thus only rely on
	the fact that the dependencies are at least unpacked and were already
	configured once (similar to what Pre-Depends ensures for preinst maintainer
	scripts). postinst triggered processes one or more triggers that this package
	is interested in. In case of failure the package's state becomes
	"Half-Configured" and the task associated to the trigger processing will be
	completed by the postinst configure during the next package's
	configuration[48].

Have a nice day,

-- 
Charles
[triggers-policy-2013-07-25.patch (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sat, 03 Aug 2013 08:03:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 03 Aug 2013 08:03:04 GMT) Full text and rfc822 format available.

Message #194 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sat, 3 Aug 2013 17:00:12 +0900
Le Thu, Jul 25, 2013 at 08:00:55AM +0900, Charles Plessy a écrit :
> 
> does the current patch (attached) address your concerns ?  If yes, would
> you second it ?

Hi all,

I would like to make one more call for feedback.

Needless to say, I am annoyed that despite we had mutiple persons who commented
in that thread, and five Policy editors with a fresh delegation, nothing is
moving forward.  Julien, Guillem, could you confirm if we can go ahead without
further input from you ?  To the other Policy editors: given the glacial pace
of the work, would it possible for at least one of you to book one hour in your
calendar within for instance the next two months, to ensure that one more
person can be in position of seconding the patch or requesting further
corrections ?

Have a nice week-end,

-- 
Charles



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sat, 03 Aug 2013 16:42:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Julien Cristau <jcristau@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 03 Aug 2013 16:42:04 GMT) Full text and rfc822 format available.

Message #199 received at 582109@bugs.debian.org (full text, mbox):

From: Julien Cristau <jcristau@debian.org>
To: Charles Plessy <plessy@debian.org>, 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sat, 3 Aug 2013 18:39:01 +0200
[Message part 1 (text/plain, inline)]
On Thu, Jul 25, 2013 at 08:00:55 +0900, Charles Plessy wrote:

> does the current patch (attached) address your concerns ?  If yes, would
> you second it ?
> 
Sorry, I don't feel confident to second anything trigger-related.

Cheers,
Julien
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sat, 03 Aug 2013 16:45:10 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jonathan Nieder <jrnieder@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 03 Aug 2013 16:45:10 GMT) Full text and rfc822 format available.

Message #204 received at 582109@bugs.debian.org (full text, mbox):

From: Jonathan Nieder <jrnieder@gmail.com>
To: Charles Plessy <plessy@debian.org>
Cc: 582109@bugs.debian.org, debian-dpkg@lists.debian.org
Subject: Re: debian-policy: document triggers where appropriate
Date: Sat, 3 Aug 2013 09:41:59 -0700
Charles Plessy wrote:
> Le Thu, Jul 25, 2013 at 08:00:55AM +0900, Charles Plessy a écrit :

>> does the current patch (attached) address your concerns ?  If yes, would
>> you second it ?
>
> Hi all,
>
> I would like to make one more call for feedback.

Sorry for the long silence.

My feeling is that the patch is not ready yet.  I know that without some
more specific list of concerns that is not a very useful thing to say,
but that's what I have.  In other words, I don't think it's ready for
seconds.

If I end up with time to work on it, what I would probably do is to
split the patch into smaller changes that can be considered and
applied independently, which would hopefully be less intimidating for
area experts to review.

For example, a patch adding documentation of the non-trigger Dpkg
states and how the package installation procedure interacts with them
should be uncontroversial and easy to review.

With triggers, one of the hardest parts to document is how packagers
are supposed to deal with the "dependencies may not be configured"
bug.  Mentioning the bug as you have is good, but giving some
practical advice about how to work around it ("Do not rely on a sane
state being present" is not practical advice because it doesn't say
what to do when your dependencies are missing) would be better.  Maybe
policy should only define the -noawait variant for now?

Thanks, and sorry I do not have something more useful to offer,
Jonathan



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sun, 04 Aug 2013 00:18:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 04 Aug 2013 00:18:04 GMT) Full text and rfc822 format available.

Message #209 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Sun, 4 Aug 2013 09:14:09 +0900
[Message part 1 (text/plain, inline)]
Le Sat, Aug 03, 2013 at 09:41:59AM -0700, Jonathan Nieder a écrit :
> 
> If I end up with time to work on it, what I would probably do is to
> split the patch into smaller changes that can be considered and
> applied independently, which would hopefully be less intimidating for
> area experts to review.

Hi Jonathan,

I have split the patch in the following parts:

	0001-Document-Dpkg-states.patch
	0002-Document-postinst-triggered.patch
	0003-Document-concepts-syntax-and-control-information-fil.patch
	0004-Detail-the-two-trigger-kinds-explicit-and-file.patch
	0005-Details-about-Dpkg-states-when-processing-triggers.patch
	0006-Document-the-behaviour-of-triggers-when-packages-are.patch

I could not cut in smaller pieces, as it would separate informations that would
lose a lot of context if they are not added together.

> With triggers, one of the hardest parts to document is how packagers
> are supposed to deal with the "dependencies may not be configured"
> bug.  Mentioning the bug as you have is good, but giving some
> practical advice about how to work around it ("Do not rely on a sane
> state being present" is not practical advice because it doesn't say
> what to do when your dependencies are missing) would be better.  Maybe
> policy should only define the -noawait variant for now?

In the current patch, the -noawait variant is recommended.  I think that the
Policy should not hide information about a feature in the hope that less people
use it.  I think that it is important that the Policy stays a neutral
reference.

About the Dpkg bug, I think that we should consider the whole section about the
postinst script.  In the paragraph above the description of "postinst
triggered" it already mentions "consider the correct error handling approach if
those actions fail".  I think that this is also the current practice for
"postinst configure", where often I sed that commands are tested for their
availability before being run.  Lastly, the current patch also mentions
"Pre-Depends", which is a robust last-ressort solution.

In the existing documentation of the dpkg triggers, the bug of dpkg is not
mentionned, so I think that this patch to the Policy represents a progress
compared with the current situation.  I still do not understand why there is so
much reluctance in enhancing our documentation.

Have a nice Sunday,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan
[0001-Document-Dpkg-states.patch (text/x-diff, attachment)]
[0002-Document-postinst-triggered.patch (text/x-diff, attachment)]
[0003-Document-concepts-syntax-and-control-information-fil.patch (text/x-diff, attachment)]
[0004-Detail-the-two-trigger-kinds-explicit-and-file.patch (text/x-diff, attachment)]
[0005-Details-about-Dpkg-states-when-processing-triggers.patch (text/x-diff, attachment)]
[0006-Document-the-behaviour-of-triggers-when-packages-are.patch (text/x-diff, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Fri, 16 Aug 2013 01:15:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 16 Aug 2013 01:15:04 GMT) Full text and rfc822 format available.

Message #214 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Fri, 16 Aug 2013 10:10:51 +0900
Le Sun, Aug 04, 2013 at 09:14:09AM +0900, Charles Plessy a écrit :
> Le Sat, Aug 03, 2013 at 09:41:59AM -0700, Jonathan Nieder a écrit :
> > 
> > If I end up with time to work on it, what I would probably do is to
> > split the patch into smaller changes that can be considered and
> > applied independently, which would hopefully be less intimidating for
> > area experts to review.
> 
> Hi Jonathan,
> 
> I have split the patch in the following parts:
> 
> 	0001-Document-Dpkg-states.patch
> 	0002-Document-postinst-triggered.patch
> 	0003-Document-concepts-syntax-and-control-information-fil.patch
> 	0004-Detail-the-two-trigger-kinds-explicit-and-file.patch
> 	0005-Details-about-Dpkg-states-when-processing-triggers.patch
> 	0006-Document-the-behaviour-of-triggers-when-packages-are.patch

Hi Jonathan and everybody,

how about starting with 0001-Document-Dpkg-states.patch ?  It documents the
Dpkg states without intrusive normative changes.

> >From 5d3279e10152d6ecb8b2b4bf226f7e7a380228e1 Mon Sep 17 00:00:00 2001
> From: Charles Plessy <plessy@debian.org>
> Date: Sun, 4 Aug 2013 07:17:03 +0900
> Subject: [PATCH 1/6] Document Dpkg states.
> 
> ---
>  policy.sgml              | 47 +++++++++++++++++++++++++++++++++++++++++++++++
>  upgrading-checklist.sgml |  4 ++++
>  2 files changed, 51 insertions(+)
> 
> diff --git a/policy.sgml b/policy.sgml
> index cb1093f..e3598f1 100644
> --- a/policy.sgml
> +++ b/policy.sgml
> @@ -3959,6 +3959,53 @@ Checksums-Sha256:
>  	</p>
>  
>  	<p>
> +	  Dpkg defines the following states for the packages.
> +	  <taglist>
> +	    <tag>Not-Installed</tag>
> +	    <item>
> +	      The package is not installed on the system.
> +	    </item>
> +
> +	    <tag>Config-Files</tag>
> +	    <item>
> +	      Only the configuration files of the package exist on the system.
> +	    </item>
> +
> +	    <tag>Half-Installed</tag>
> +	    <item>
> +	      The installation of the package has been started, but not
> +	      completed for some reason.
> +	    </item>
> +
> +	    <tag>Unpacked</tag>
> +	    <item>
> +	      The package is unpacked, but not configured.
> +	    </item>
> +
> +	    <tag>Half-Configured</tag>
> +	    <item>
> +	      The package is unpacked and its configuration or the processing
> +	      of one of its triggers has not yet completed for some reason.
> +	    </item>
> +
> +	    <tag>Triggers-Awaited</tag>
> +	    <item>
> +	      The package awaits trigger processing by another package.
> +	    </item>
> +
> +	    <tag>Triggers-Pending</tag>
> +	    <item>
> +	      The package has been triggered.
> +	    </item>
> +
> +	    <tag>Installed</tag>
> +	    <item>
> +	      The package is unpacked and configured.
> +	    </item>
> +	  </taglist>
> +	</p>
> +
> +	<p>
>  	  Broadly speaking the <prgn>preinst</prgn> is called before
>  	  (a particular version of) a package is unpacked, and the
>  	  <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
> diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml
> index 0a111d4..41a1e84 100644
> --- a/upgrading-checklist.sgml
> +++ b/upgrading-checklist.sgml
> @@ -55,6 +55,10 @@ Unreleased.
>    <item>New section documenting the <tt>Package-Type</tt> field in source
>    package control files.
>    </item>
> +<tag>6.1</tag>
> +  <item>The Dpkg states are now documented.  The Policy has been proofread
> +  and occurences of "Failed-Config" have been corrected to "Half-Configured".
> +  </item>
>  <tag>11.5.2</tag>
>    <item>Stop recommending to serve HTML documents from
>    <file>/usr/share/doc/<var>package</var></file>.
> -- 
> 1.8.4.rc0
> 

Have a nice day,

-- 
Charles



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Sat, 24 Aug 2013 01:39:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 24 Aug 2013 01:39:04 GMT) Full text and rfc822 format available.

Message #219 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: Ian Jackson <ijackson@chiark.greenend.org.uk>, 582109@bugs.debian.org
Subject: Review of the patches to document triggers in the Policy.
Date: Sat, 24 Aug 2013 10:36:46 +0900
Le Fri, Aug 23, 2013 at 12:44:36PM +0100, Ian Jackson a écrit :
> Charles Plessy writes ("Re: Bug#720507: .dsc field for dgit"):
> 
> > PS: off-topic question: do you have comments to make about the documentation
> > of Dpkg's triggers to the Policy ?
> 
> I'm afraid I haven't had a chance to review that.  Is it any different
> in semantics to the original triggers text file document ?

We have not changed the semantics compared to the current documentation (that
includes the "noawait" variants that were not present in the original
proposal).  The documentation in the Policy brings together informations from
deb-triggers(5), dpkg-trigger(1) and /usr/share/doc/dpkg-dev/triggers.txt.gz.
Most of the text is a direct copy or adaptation from these three documents,
plus an extra paragraph listing the Dpkg states, taken from dpkg(1).  From
/usr/share/doc/dpkg-dev/triggers.txt.gz, I left out the historical details
(plan for transition, etc.), implementation details, discussions regarding apt,
etc., basically most of the text after the section "File triggers".

The latest patches are in the following message in the BTS.  If you had time
to review them, that would be great !

    http://bugs.debian.org/582109#209 

Cheers,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#582109; Package debian-policy. (Mon, 14 Oct 2013 05:36:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Mon, 14 Oct 2013 05:36:04 GMT) Full text and rfc822 format available.

Message #224 received at 582109@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: Charles Plessy <plessy@debian.org>, 582109@bugs.debian.org
Cc: debian-dpkg@lists.debian.org
Subject: Re: Bug#582109: debian-policy: document triggers where appropriate
Date: Mon, 14 Oct 2013 14:32:58 +0900
Le Fri, Aug 16, 2013 at 10:10:51AM +0900, Charles Plessy a écrit :
> Le Sun, Aug 04, 2013 at 09:14:09AM +0900, Charles Plessy a écrit :
> > Le Sat, Aug 03, 2013 at 09:41:59AM -0700, Jonathan Nieder a écrit :
> > > 
> > > If I end up with time to work on it, what I would probably do is to
> > > split the patch into smaller changes that can be considered and
> > > applied independently, which would hopefully be less intimidating for
> > > area experts to review.
> > 
> > Hi Jonathan,
> > 
> > I have split the patch in the following parts:
> > 
> > 	0001-Document-Dpkg-states.patch
> > 	0002-Document-postinst-triggered.patch
> > 	0003-Document-concepts-syntax-and-control-information-fil.patch
> > 	0004-Detail-the-two-trigger-kinds-explicit-and-file.patch
> > 	0005-Details-about-Dpkg-states-when-processing-triggers.patch
> > 	0006-Document-the-behaviour-of-triggers-when-packages-are.patch
> 
> Hi Jonathan and everybody,
> 
> how about starting with 0001-Document-Dpkg-states.patch ?  It documents the
> Dpkg states without intrusive normative changes.

Hi all,

this is the last call for integrating Dpkg triggers in the next update of the
Policy.  (3.9.5), that I inted to upload before the end of October.

Cheers,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan



Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Mon Apr 21 02:06:23 2014; Machine Name: beach.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.