From ed947ae43dc48d4bee1b609fe3942ff1a01e7a6b Mon Sep 17 00:00:00 2001
From: Luca Boccassi <bluca@debian.org>
Date: Mon, 8 May 2023 03:21:14 +0100
Subject: [PATCH] Forbid using dpkg-divert/alternatives when there are native
 mechanisms

The supported mechanism for augmenting, changing, overriding and
disabling systemd configuration files is natively supported and fully
integrated in Debian, via drop-ins, hierarchical overrides, and
masking. dpkg-divert is not integrated in systemd tools so its use
is completely hidden in logs and status interfaces, and it is specific
to Debian and thus diverges from what users expect as implemented by
all other distros, going against one of the core goals of the systemd
project which is to provide a uniform interface regardless of distro
vendor or flavour.

Clarify that diversions and alternatives should only be used when
needed, with cooperation, and must not be used when there are native
mechanisms to obtain the same goals, and use systemd files as an
example.
---
 policy/ap-pkg-alternatives.rst |  3 +++
 policy/ap-pkg-diversions.rst   |  3 +++
 policy/ch-binary.rst           | 35 ++++++++++++++++++++++++++++++++++
 3 files changed, 41 insertions(+)

diff --git a/policy/ap-pkg-alternatives.rst b/policy/ap-pkg-alternatives.rst
index ffa2163..6f7780f 100644
--- a/policy/ap-pkg-alternatives.rst
+++ b/policy/ap-pkg-alternatives.rst
@@ -24,3 +24,6 @@ See the :manpage:`update-alternatives(8)` man page for details.
 If ``update-alternatives`` does not seem appropriate you may wish to
 consider using diversions instead.
 
+Do not use alternatives for ``systemd`` configuration files. See
+:doc:`ch-binary` for more information.
+
diff --git a/policy/ap-pkg-diversions.rst b/policy/ap-pkg-diversions.rst
index fe360d1..d299d04 100644
--- a/policy/ap-pkg-diversions.rst
+++ b/policy/ap-pkg-diversions.rst
@@ -81,3 +81,6 @@ when the file does not exist.
 Do not attempt to divert a conffile, as ``dpkg`` does not handle it
 well.
 
+Do not use diversions for files that have their own native override mechanisms,
+such as ``systemd`` unit files. See :doc:`ch-binary` for more information.
+
diff --git a/policy/ch-binary.rst b/policy/ch-binary.rst
index e517f26..19635e7 100644
--- a/policy/ch-binary.rst
+++ b/policy/ch-binary.rst
@@ -371,6 +371,41 @@ against earlier versions of something that previously did not use
 ``update-alternatives``; this is an exception to the usual rule that
 versioned conflicts should be avoided.)
 
+Diversions are primarily intended as a tool for local administrators or local
+packages to override the behavior of Debian. While there are some circumstances
+where one Debian package may need to divert a file of another Debian package,
+those circumstances are rare and diversions should only be used as a last resort
+when no other suitable mechanism exists. Diversion of a file in one Debian
+package by another Debian package should be coordinated between the maintainers
+of those packages. Maintainers should strongly prefer using other overriding
+mechanisms, instead of diversions, whenever those other mechanisms are
+sufficient to accomplish the same goal. In other words, diversions in packages
+should be considered a last resort.
+
+One specific case of that rule is that configuration files used by
+``systemd`` components, such as `units,
+<https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description>`_
+`udev rules,
+<https://www.freedesktop.org/software/systemd/man/udev.html#Rules%20Files>`_
+`tmpfiles.d,
+<https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html#Configuration%20Directories%20and%20Precedence>`_
+`modules-load.d,
+<https://www.freedesktop.org/software/systemd/man/modules-load.d.html#Configuration%20Format>`_,
+`sysusers
+<https://www.freedesktop.org/software/systemd/man/sysusers.d.html#Configuration%20Directories%20and%20Precedence>`_
+and other such files, including those specific to systemd daemons
+(e.g.:  `/etc/systemd/system.conf).
+<https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html>`_
+must not be diverted by any Debian package. Instead, use `masking and drop-ins
+<https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description>`_.
+
+Alternatives must never be used for ``systemd`` configuration files. The
+alternatives system does not know how to apply changes to services when updating
+alternatives, so the resulting behavior would be confusing and unpredictable.
+Instead, `aliases
+<https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description>`_
+can be used to provide alternative implementations of the same named unit.
+
 .. _s-maintscriptprompt:
 
 Prompting in maintainer scripts
-- 
2.39.2

