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 f57a498..b747c0b 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -587,6 +587,15 @@
         </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
           hierarchy of object paths that start with