Bug 98671 - auto-starting and SystemdService are not documented in the spec
Summary: auto-starting and SystemdService are not documented in the spec
Status: RESOLVED FIXED
Alias: None
Product: dbus
Classification: Unclassified
Component: core (show other bugs)
Version: git master
Hardware: Other All
: medium normal
Assignee: Simon McVittie
QA Contact: D-Bus Maintainers
URL:
Whiteboard: review?
Keywords: patch
Depends on:
Blocks: 98666
  Show dependency treegraph
 
Reported: 2016-11-10 11:54 UTC by Simon McVittie
Modified: 2016-11-22 19:03 UTC (History)
1 user (show)

See Also:
i915 platform:
i915 features:


Attachments
Spec: be clearer about what activation means (1.66 KB, patch)
2016-11-21 20:35 UTC, Simon McVittie
Details | Splinter Review
Spec: document what auto-starting is, and recommend it (5.20 KB, patch)
2016-11-21 20:36 UTC, Simon McVittie
Details | Splinter Review
Spec: document systemd activation (2.32 KB, patch)
2016-11-21 20:36 UTC, Simon McVittie
Details | Splinter Review
Spec: mostly use versioned interface and bus names (6.93 KB, patch)
2016-11-21 20:37 UTC, Simon McVittie
Details | Splinter Review
Spec: be clearer about "starting" and "activation" being synonyms (1.74 KB, patch)
2016-11-22 11:47 UTC, Simon McVittie
Details | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Simon McVittie 2016-11-10 11:54:04 UTC
While working on Bug #98666 I noticed that hte spec doesn't really define what "auto-starting" means, and doesn't document the SystemdService key that can appear in D-Bus service files.

Patches are on Bug #98666, because they patch the same part of the spec where I added AssumedAppArmorLabel. Please review there if interested.
Comment 1 Philip Withnall 2016-11-12 23:40:53 UTC
> Please review there if interested.

Interested. Reviewed there.
Comment 2 Simon McVittie 2016-11-21 20:35:27 UTC
Created attachment 128107 [details] [review]
Spec: be clearer about what activation means

The spec previously mentioned that CORBA calls this activation, but
did not explicitly say that D-Bus has copied this jargon term.
It's 2016, and developers are probably more likely to be familiar
with D-Bus than with CORBA at this point: explicitly say that *our*
jargon term for this action is activation.

---

This is mainly a response to the suggestion on Bug #98666 that the meaning of "activation" was insufficiently clear.
Comment 3 Simon McVittie 2016-11-21 20:36:13 UTC
Created attachment 128108 [details] [review]
Spec: document what auto-starting is, and recommend it

For something we recommend, that is important enough to have its own
header flag, it doesn't have very good documentation. Redo the text
to suggest that auto-starting is the normal thing and
StartServiceByName is the oddity. That's usually a good principle
to follow, since it dodges time-of-check/time-of-use issues, and the
method call that you presumably wanted to do needs to handle errors
anyway.

---

Supersedes Attachment #127878 [details]
Comment 4 Simon McVittie 2016-11-21 20:36:58 UTC
Created attachment 128109 [details] [review]
Spec: document systemd activation

We didn't say that SystemdService existed. Now we do, together with
enough context to make it make sense.

---

Supersedes Attachment #127879 [details]. Philip already reviewed this one.
Comment 5 Simon McVittie 2016-11-21 20:37:28 UTC
Created attachment 128110 [details] [review]
Spec: mostly use versioned interface and bus names

Using versioned names here reinforces the advice given in
<https://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning>.

I haven't added versions to the sample parameters "com.example.tea" and
"com.example.cappuccino" for methods that query information about
names, on the basis that I assume they are more likely to be intended
to represent an implementation than an API.

---

As Philip suggested on Bug #98666.
Comment 6 Philip Withnall 2016-11-21 20:59:26 UTC
Comment on attachment 128107 [details] [review]
Spec: be clearer about what activation means

Review of attachment 128107 [details] [review]:
-----------------------------------------------------------------

Looks good.
Comment 7 Philip Withnall 2016-11-21 21:02:31 UTC
Comment on attachment 128108 [details] [review]
Spec: document what auto-starting is, and recommend it

Review of attachment 128108 [details] [review]:
-----------------------------------------------------------------

r+
Comment 8 Philip Withnall 2016-11-21 21:03:08 UTC
Comment on attachment 128109 [details] [review]
Spec: document systemd activation

Review of attachment 128109 [details] [review]:
-----------------------------------------------------------------

r+ as before.
Comment 9 Philip Withnall 2016-11-21 21:04:13 UTC
Comment on attachment 128110 [details] [review]
Spec: mostly use versioned interface and bus names

Review of attachment 128110 [details] [review]:
-----------------------------------------------------------------

+1, all over the specification.
Comment 10 Simon McVittie 2016-11-22 11:29:31 UTC
Fixed in git for spec 0.30 (dbus 1.11.8). Thanks for reviewing.
Comment 11 Simon McVittie 2016-11-22 11:45:56 UTC
Reopening, one more patch...
Comment 12 Simon McVittie 2016-11-22 11:47:08 UTC
Created attachment 128143 [details] [review]
Spec: be clearer about "starting" and "activation" being  synonyms

---

Philip, does this address your concern on Bug #98666 about it being insufficiently clear that "activation" and "starting" are the same thing?
Comment 13 Philip Withnall 2016-11-22 12:52:14 UTC
Comment on attachment 128143 [details] [review]
Spec: be clearer about "starting" and "activation" being  synonyms

Review of attachment 128143 [details] [review]:
-----------------------------------------------------------------

r+
Comment 14 Simon McVittie 2016-11-22 19:03:28 UTC
Fixed (again) for spec 0.30, 1.11.8


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.