Merge lp:~jdstrand/snappy/snappy.bus-name-docs into lp:~snappy-dev/snappy/snappy-moved-to-github

[Jamie Strandboge]

docs/frameworks.md: discuss `bus-name`
docs/meta.md:
- whitespace
- reference frameworks.md in bus-name

[lp:~jdstrand/snappy/snappy.bus-name-docs]

453. By Jamie Strandboge on 2015-05-12

merge from trunk

454. By Jamie Strandboge on 2015-05-12

docs/frameworks.md: quote vendor

[Jamie Strandboge (jdstrand)]

Per irc discussion with mterry, after fixing the quoting, it's ok.

review: Approve

=== modified file 'docs/frameworks.md'
--- docs/frameworks.md	2015-04-23 15:07:47 +0000
+++ docs/frameworks.md	2015-05-12 17:39:46 +0000
@@ -65,15 +65,17 @@
 ## Usage
 ### framework yaml
 
-For frameworks, meta/package.yaml should contain something like:
+For frameworks, meta/package.yaml might contain something like:
 
     name: foo
     version: 1.1.234
+    vendor: "Some Person <[e-mail]>"
     type: framework
     services:
       - name: bar
         description: "desc for bar service"
         start: bin/bar
+        bus-name: com.example.foo
     binaries:
       - name: bin/baz
         description: "desc for baz binary"
@@ -82,6 +84,21 @@
 
 * `type: framework` - defines the type of snap this is
 
+#### DBus connection name
+For framework services that provide a DBus interface, use `bus-name` to specify
+the DBus connection name the service will bind to on the system bus (only
+`^[A-Za-z0-9][A-Za-z0-9_-]*(\.[A-Za-z0-9][A-Za-z0-9_-]*)+$` is allowed). To
+preserve coinstallability, the `bus-name` should typically use the form of one
+of the following: `<name>`, `<name>.<service name>`, `<reverse domain>.<name>`
+or `<reverse domain>.<name>.<service name>`. In the above yaml, any of the
+following can be used:
+
+* `bus-name: foo`
+* `bus-name: foo.bar`
+* `bus-name: com.example.foo`
+* `bus-name: com.example.foo.bar`
+
+#### Security policy
 Frameworks will typically need specialized security policy. See `security.md`
 for details.
 
 
=== modified file 'docs/meta.md'
--- docs/meta.md	2015-04-22 13:42:03 +0000
+++ docs/meta.md	2015-05-12 17:39:46 +0000
@@ -1,7 +1,7 @@
 # Package metadata
 
 This document describes the meta data of a snappy package. All files
-are located under the `meta/` directory. 
+are located under the `meta/` directory.
 
 The following files are supported:
 
@@ -50,7 +50,7 @@
    * `caps`: (optional) list of additional security policies to add.
              See `security.md` for details
    * `security-template`: (optional) alternate security template to use
-                          instead of `default`. See `security.md` for details 
+                          instead of `default`. See `security.md` for details
    * `security-override`: (optional) high level overrides to use when
                           `security-template` and `caps` are not
                           sufficient.  See security.md for details
@@ -68,7 +68,8 @@
          * `port`: (optional) see above
          * `negotiable`: (optional) see above
    * `bus-name`: (optional) message bus connection name for the service.
-     May only be specified for snaps of 'type: framework' (see above).
+     May only be specified for snaps of 'type: framework' (see above). See
+     frameworks.md for details.
 
  * `binaries`: the binaries (executables) that the snap provides
    * `name`: (required) the name of the binary, the user will be able to
@@ -78,8 +79,8 @@
    * `caps`: (optional) see entry in `services` (above)
    * `security-template`: (optional) see entry in `services` (above)
    * `security-override`: (optional) see entry in `services` (above)
-   * `security-policy`: (optional) see entry in `services` (above)   
- 
+   * `security-policy`: (optional) see entry in `services` (above)
+
 ## license.txt
 
 A license text that the user must accept before the snap can be