#192 Please add recommendation for Documentation= fields in unit files to the policy
Closed: Fixed None Opened 11 years ago by lennart.

systemd has now the ability to link up units with their respective documentation. It would be great if the packaging policy would suggest making use of this in unit files.

More specifically I'd like to see a recommendation to use Documentation= assignments in the [Unit] section (right next to Description=).

Why this is cool is documented in this blog story:

http://0pointer.de/blog/projects/self-documented-boot.html

And the documentation for this field you find in the man page:

http://www.freedesktop.org/software/systemd/man/systemd.unit.html


Can't reach 0pointer.de as of this writing. Interesting idea though. What sort of value for the field do you propose that we recommend? I'd assume that admins would know where to look on-system for docs (man, /usr/shar/doc, etc) but this could be useful for http resources.

Tentative +1.

Replying to [comment:1 limb]:

Can't reach 0pointer.de as of this writing. Interesting idea though. What sort of value for the field do you propose that we recommend? I'd assume that admins would know where to look on-system for docs (man, /usr/shar/doc, etc) but this could be useful for http resources.

Tentative +1.

0pointer.de should be back now.

My recommendation would probably be to prefer man: over http://, if both exist for the same text (and definitely not list both URLs). And order them in order of relevance, and put the texts with the answer for "What is this?" before "How do I configure this?"

Spot's new wording draft approved (+1:5, 0:1, -1:0)

"Fedora 18+ versions of systemd have support for defining documentation in unit files (it is ignored in older releases, so it is safe to keep one systemd unit file across all branches). Whenever possible, please include a Documentation= field in your unit file which points to available documentation describing the service being run. If a man page or info page is present in the package, refer to it using "man:manpage" or "info:infofile" respectively. If the documentation is in plaintext, use "file://path/to/file". Lastly, if no local documentation exists in the package, but it exists at a url, use the URL (with http://) in this field. Multiple URIs can be added to the Documentation= field, as a space separated list. For details on URI definitions and formatting, please refer to the uri(7) manpage (man uri)."

Lennart, please advise us if there are any issues with using Documentation= in unit files in older systemd environments (F16/F17), our testing did not show any. Also, if you backport this feature to older systemd versions (F16/F17), please advise us so we can adjust the guidelines appropriately.

Replying to [comment:3 spot]:

Spot's new wording draft approved (+1:5, 0:1, -1:0)

"Fedora 18+ versions of systemd have support for defining documentation in unit files (it is ignored in older releases, so it is safe to keep one systemd unit file across all branches). Whenever possible, please include a Documentation= field in your unit file which points to available documentation describing the service being run. If a man page or info page is present in the package, refer to it using "man:manpage" or "info:infofile" respectively. If the documentation is in plaintext, use "file://path/to/file". Lastly, if no local documentation exists in the package, but it exists at a url, use the URL (with http://) in this field. Multiple URIs can be added to the Documentation= field, as a space separated list. For details on URI definitions and formatting, please refer to the uri(7) manpage (man uri)."

I'd like to see explicitly mentioned that the documentation should: a) answer the question "what is this?", b) answer the question "how do i configure this?" and c) list auxiliary docs if any and relevant.

And the spec should probably also suggest to list the docs in exactly the order a, b, c, above.

Lennart, please advise us if there are any issues with using Documentation= in unit files in older systemd environments (F16/F17), our testing did not show any. Also, if you backport this feature to older systemd versions (F16/F17), please advise us so we can adjust the guidelines appropriately.

This is supported already in F17. We could backport this to F16 if really desired. (If so, somebody should open a bz bug for this).

Without the backport you'll just get warnings in the logs, but everything will work fine. The warnings will look something like "Unknown directive Documentation=, ignoring." or so.

Replying to [comment:4 lennart]:

I'd like to see explicitly mentioned that the documentation should: a) answer the question "what is this?", b) answer the question "how do i configure this?" and c) list auxiliary docs if any and relevant.

And the spec should probably also suggest to list the docs in exactly the order a, b, c, above.

By example, here is what we have for systemd-logind.service:

{{{
Documentation=man:systemd-logind.service(8) man:logind.conf(5) http://www.freedesktop.org/wiki/Software/systemd/multiseat
}}}

The first linked man page generally describes what the service is for. The second page is about the service's configuration file, and the third URL refers to some general documentation explaining where logind fits into the big picture.

I'd be happy if we'd suggest the same kind of complete docs for all services.

FPC approved this additional set of sentences for the policy:

"System administrators will be looking at the Documentation= field to determine what the service is, how to configure it, and where to locate additional documentation relating to the service. Accordingly, packagers are strongly encouraged to include any available sources in the Documentation= field which provide this information."

(+1:5 , 0:0, -1:0)

Announce text:

A new section on the Documentation= field in systemd unit files (F17+) has been added.

https://fedoraproject.org/wiki/Packaging:Systemd#Documentation_field

Metadata Update from @spot:
- Issue assigned to spot

7 years ago

Login to comment on this ticket.

Metadata