Officially deprecate package-supplied dbus-daemon policy in ${sysconfdir}

Now that dbus 1.10 has become widely available, we should start to
treat ${sysconfdir} as reserved for the sysadmin, and encourage
third-party software packages to install their integration files into
${datadir}.

Signed-off-by: Simon McVittie <smcv@collabora.com>

diff --git a/NEWS b/NEWS
index 112d196c030f19c5c33557a766820a65bd0f553c..349b2e9f8b9f647fd3d13aafb0670dd5fa9d3366 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,21 @@
 dbus 1.13.10 (UNRELEASED)
 =========================
 
+Deprecations:
+
+• Third-party software should install default dbus policies for the system
+  bus into ${datadir}/dbus-1/system.d (this has been supported since dbus
+  1.10, released in August 2015). Installing default dbus policies in
+  ${sysconfdir}/dbus-1/system.d is now considered to be deprecated. Policy
+  files in ${sysconfdir}/dbus-1/system.d continue to be read, but this
+  directory should only be used by system administrators wishing to
+  override the default policies.
+
+  The ${datadir} applicable to dbus is usually /usr/share and the
+  ${sysconfdir} is usually /etc.
+
+• A similar pattern applies to the session bus policies in session.d.
+
 Fixes:
 
 • Avoid possible memory corruption in certain DBusHashTableIter use

diff --git a/doc/dbus-daemon.1.xml.in b/doc/dbus-daemon.1.xml.in
index 526b85ba71b82cdaca513dd1ef0a9fdd667cccef..70a8fb3d487ca47f750d4c3353b68d09430c4cf1 100644 (file)
--- a/doc/dbus-daemon.1.xml.in
+++ b/doc/dbus-daemon.1.xml.in
@@ -223,6 +223,21 @@ configured in the files "@EXPANDED_DATADIR@/dbus-1/system.conf" and
 overrides in those files to avoid modifying the primary configuration
 files.</para>
 
+<para>The standard system bus normally reads additional XML files from
+  <filename>@EXPANDED_DATADIR@/dbus-1/system.d</filename>. Third-party
+  packages should install the default policies necessary for correct
+  operation into that directory, which has been supported since dbus 1.10
+  (released in 2015).</para>
+
+<para>The standard system bus normally also reads XML files from
+  <filename>@EXPANDED_SYSCONFDIR@/dbus-1/system.d</filename>, which
+  should be used by system administrators if they wish to override
+  default policies.</para>
+
+<para>Third-party packages would historically install XML files into
+  <filename>@EXPANDED_SYSCONFDIR@/dbus-1/system.d</filename>, but this
+  practice is now considered to be deprecated: that directory should
+  be treated as reserved for the system administrator.</para>
 
 <para>The configuration file is an XML document. It must have the following
 doctype declaration:</para>
@@ -302,12 +317,10 @@ to be absent.</para>
 point. Files in the directory are included in undefined order.
 Only files ending in ".conf" are included.</para>
 
-
 <para>This is intended to allow extension of the system bus by particular
 packages. For example, if CUPS wants to be able to send out
 notification of printer queue changes, it could install a file to
-@EXPANDED_DATADIR@/dbus-1/system.d or
-@EXPANDED_SYSCONFDIR@/dbus-1/system.d that allowed all apps to receive
+@EXPANDED_DATADIR@/dbus-1/system.d that allowed all apps to receive
 this message and allowed the printer daemon user to send it.</para>
 
 <itemizedlist remap='TP'>