Re: Updated maint-guide contents, question on style

[Jonathan Nieder <jrnieder@gmail.com>]

Justin B Rye wrote:

> In 7.1, the solutions suggested for a file collision are (a) using
> alternatives, (b) coordinating with other affected packages, and (c)
> using a Conflicts.  It seems to me that (a) is a subcategory of (b);
> you can't set up alternatives unilaterally, can you?

I think the original meant to say that the outcome could be
(a) alternatives or (b) a Conflicts, and that in the former case it
happens via coordination with the maintainers of the other packages.

> I've rephrased
> the text to mention (c) first, then (b), giving (a) as an example.
> But then what about the omitted option (d), just patching the package
> to rename the relevant file?

Thus I suspect it might be better to mention (e) [let one package,
possibly a new one, take care of providing the file] first, then (d),
then (a), then (c)?  I don't think the maint-guide should encourage
use of diversions as a way to steal a filename from another package,
so pretending that the alternatives system is the only way for
multiple packages to provide a resource with the same filename doesn't
seem so bad.

While a file conflict can be a symptom of a semantic conflict that
should be declared with Conflicts, using Conflicts to work around a
namespace clash is strongly discouraged (so it is tempting to keep it
last).

> --- maint-guide.en.dbk.pristine	2011-04-17 14:35:41.052916002 +0100
> +++ maint-guide.en.dbk	2011-04-26 23:15:04.017256444 +0100
> @@ -4240,48 +4240,49 @@
[...]
>  <para>
> -You have to make sure that there are no overlapped files with other existing
> -packages using the
> +To prevent installation problem on different systems, you must make
> +sure that there are no filenames conflict with other existing packages,

"filename conflicts" or "filenames conflicting", I think.

> +are collisions, please take action to avoid this real problem, whether by
> +declaring a <literal>Conflicts</literal> relationship in the
> +<filename>debian/control</filename> file or by coordinating with other
> +affected packages, for instance to use the alternatives mechanism (see
> +<citerefentry> <refentrytitle>update-alternatives</refentrytitle>
> +<manvolnum>1</manvolnum> </citerefentry>).

Maybe:

 are collisions, please take action to avoid this real problem, whether by
 renaming the file, moving a common file to a separate package
 multiple packages can depend on, using the alternatives mechanism (see
 <citerefentry><refentrytitle>update-alternatives</refentrytitle>
 <manvolnum>1</manvolnum></citereferentry>) in coordination with the
 maintainers of other affected packages, or declaring a
 <literal>Conflicts</literal> relationship in the
 <filename>debian/control</filename> file.

> -All <emphasis>maintainer scripts</emphasis>, i.e.,
> +All maintainer scripts (that is,
>  <filename>preinst</filename>, <filename>prerm</filename>,
> -<filename>postinst</filename>, and <filename>postrm</filename> files, are
> -non-trivial unless they are auto-generated by the <systemitem role="package">debhelper</systemitem> programs.  So do not use them if you are
> +<filename>postinst</filename>, and <filename>postrm</filename> files) are
> +potentially problematic unless they are auto-generated by the
> +<systemitem role="package">debhelper</systemitem> programs.  So do not use them if you are
>  a novice maintainer (see <xref linkend="maintscripts"/>).

I suppose "potentially problematic" means "hard to write correctly".

Thanks for a pleasant read.
Jonathan