Bug#582109: debian-policy: document triggers where appropriate

[Raphaël Hertzog]

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

--
To UNSUBSCRIBE, email to debian-bugs-...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listm...@lists.debian.org

[sean finney]

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

[Charles Plessy]

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

[Charles Plessy]

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

[Charles Plessy]

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.

[Guillem Jover]

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

[Charles Plessy]

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]

Hello everybody,

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

[Charles Plessy]

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

[Raphael Hertzog]

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 <ple...@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/

[Russ Allbery]

Raphael Hertzog <her...@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 (r...@debian.org) <http://www.eyrie.org/~eagle/>

[Raphael Hertzog]

On Wed, 10 Apr 2013, Russ Allbery wrote:
> Raphael Hertzog <her...@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/

[Bill Allombert]

> 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. <ball...@debian.org>

Imagine a large red swirl here.

[Charles Plessy]

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

[Raphael Hertzog]

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>

[Charles Plessy]

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 :

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

[Raphael Hertzog]

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.

[Charles Plessy]

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

[Raphael Hertzog]

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/

[Charles Plessy]

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

[Charles Plessy]

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

[Julien Cristau]

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

[Charles Plessy]

Le Tue, Jul 16, 2013 at 05:09:08PM +0200, Julien Cristau a �crit :

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.

[Raphael Hertzog]

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/

[Charles Plessy]

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

[Charles Plessy]

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

[Charles Plessy]

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

[Raphael Hertzog]

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/

[Raphael Hertzog]

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/

[Charles Plessy]

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

[Raphael Hertzog]

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/

[Charles Plessy]

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,

[Raphael Hertzog]

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.

[Charles Plessy]

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

[Julien Cristau]

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

[Charles Plessy]

Le Wed, Jul 24, 2013 at 03:58:04PM +0200, Julien Cristau a �crit :

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

[Charles Plessy]

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

[Julien Cristau]

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

[Jonathan Nieder]

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

[Charles Plessy]

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]

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

[Charles Plessy]

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