Attachment 135726 Details for Bug 103914 – spec: Deprecate hyphen/minus in well-known names

[patch] spec: Deprecate hyphen/minus in well-known names

0001-spec-Deprecate-hyphen-minus-in-well-known-names.patch (text/plain), 4.59 KB, created by Simon McVittie on 2017-11-26 11:54:04 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2017-11-26 11:54:04 UTC

Size: 4.59 KB

patch

obsolete

>From 5f6a9499408cb86e16cbcaba5d06f97480cf0f69 Mon Sep 17 00:00:00 2001
>From: Simon McVittie <smcv@collabora.com>
>Date: Sun, 26 Nov 2017 11:40:51 +0000
>Subject: [PATCH] spec: Deprecate hyphen/minus in well-known names
>
>We don't really need two parallel forms of punctuation, and in
>particular DNS domain names only have one (hyphens). If we choose one
>representation and deprecate the other, it makes the recommendation
>clearer for app authors.
>
>This reflects a similar change to the Desktop Entry Specification,
>which uses D-Bus well-known names as app IDs. While hyphens are not a
>problem for D-Bus well-known names or for freedesktop.org app IDs,
>they create problems for adjacent APIs and specifications that want to
>use a well-known name in a context where hyphens are not allowed.
>Hyphens are not allowed in D-Bus object paths and interface names,
>are only conditionally allowed in Flatpak app IDs (they can only
>appear in the last element), and have a special syntactic role in
>Freedesktop icon names.
>
>Signed-off-by: Simon McVittie <smcv@collabora.com>
>Bug: https://bugs.freedesktop.org/show_bug.cgi?id=103216
>---
> doc/dbus-specification.xml | 39 ++++++++++++++++++++++++++++++++++++---
> 1 file changed, 36 insertions(+), 3 deletions(-)
>
>diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
>index c33f0a0c..860b10d7 100644
>--- a/doc/dbus-specification.xml
>+++ b/doc/dbus-specification.xml
>@@ -1793,6 +1793,17 @@
>           <literal>com.example.MusicPlayer1.Seekable</literal>.
>         </para>
> 
>+        <para>
>+          If the author's DNS domain name contains hyphen/minus characters
>+          ('-'), which are not allowed in D-Bus interface names, they
>+          should be replaced by underscores. If the DNS domain name
>+          contains a digit immediately following a period ('.'), which
>+          is also not allowed in interface names), the interface name
>+          should add an underscore before that digit. For example, if
>+          the owner of 7-zip.org defined an interface for out-of-process
>+          plugins, it might be named <literal>org._7_zip.Plugin</literal>.
>+        </para>
>+
>         <para>
>           D-Bus does not distinguish between the concepts that would be
>           called classes and interfaces in Java: either can be identified on
>@@ -1822,7 +1833,8 @@
>                 </para>
>             </listitem>
>             <listitem><para>Each element must only contain the ASCII characters
>-                "[A-Z][a-z][0-9]_-". Only elements that are part of a unique
>+                "[A-Z][a-z][0-9]_-", with "-" discouraged in new bus
>+                names. Only elements that are part of a unique
>                 connection name may begin with a digit, elements in
>                 other bus names must not begin with a digit.
>                 </para>
>@@ -1837,8 +1849,20 @@
>           </itemizedlist>
>         </para>
>         <para>
>-          Note that the hyphen ('-') character is allowed in bus names but
>-          not in interface names.
>+          Note that the hyphen ('-') character is allowed in bus names
>+          but not in interface names. It is also problematic or not
>+          allowed in various specifications and APIs that refer to
>+          D-Bus, such as <ulink
>+            url="http://docs.flatpak.org/en/latest/introduction.html#identifiers"
>+            >Flatpak application IDs</ulink>,
>+          <ulink
>+            url="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus"
>+            >the <literal>DBusActivatable</literal> interface in the
>+            Desktop Entry Specification</ulink>, and the convention
>+          that an application's "main" interface and object path
>+          resemble its bus name. To avoid situations that require
>+          special-case handling, it is recommended that new D-Bus names
>+          consistently replace hyphens with underscores.
>         </para>
> 
>         <para>
>@@ -1853,6 +1877,15 @@
>           simultaneously if backwards compatibility is required.
>         </para>
> 
>+        <para>
>+          As with interface names, if the author's DNS domain name
>+          contains hyphen/minus characters they should be replaced by
>+          underscores, and if it contains leading digits they should be
>+          escaped by prepending an underscore. For example, if the owner
>+          of 7-zip.org used a D-Bus name for an archiving application,
>+          it might be named <literal>org._7_zip.Archiver</literal>.
>+        </para>
>+
>         <para>
>           If a well-known bus name implies the presence of a "main" interface,
>           that "main" interface is often given the same name as
>-- 
>2.15.0
>

Actions: View | Splinter Review

Attachments on bug 103914: 135726

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.