From: Philip Withnall <philip.withnall@collabora.co.uk>
Date: Sat, 1 Oct 2016 11:22:30 +0000 (+0200)
Subject: spec: Recommend against using ‘/’ for object paths
X-Git-Tag: dbus-1.11.6~15
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bfebafc256bd3280b235bcbf46691f25a0acf55f;p=thirdparty%2Fdbus.git

spec: Recommend against using ‘/’ for object paths

As discussed in http://0pointer.de/blog/projects/versioning-dbus.html
and in https://dbus.freedesktop.org/doc/dbus-api-design.html,
un-versioned object paths make it hard to work out which interface a
signal was emitted from.

Clarify this in the specification to try and avoid people making this
mistake.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=37095
Reviewed-by: Simon McVittie <smcv@debian.org>
---

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index f57a49830..b747c0bfe 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -586,6 +586,15 @@
           plugins).
         </para>
 
+        <para>
+          Using an object path of <literal>/</literal> is allowed, but
+          recommended against, as it makes versioning of interfaces hard. Any
+          signals emitted from a D-Bus object have the service’s unique bus name
+          associated with them, rather than its well-known name. This means that
+          receipients of the signals must rely entirely on the signal name and
+          object path to work out which interface the signal originated from.
+        </para>
+
         <para>
           For instance, if the owner of <literal>example.com</literal> is
           developing a D-Bus API for a music player, they might use the