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 f57a4983074c2f22ae4486245e08909c40cbd14f..b747c0bfee106465e68e1f4cf526c597e078f560 100644 (file)
--- 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