Ticket #192 (closed enhancement: fixed)

Opened 22 months ago

Last modified 21 months ago

Please add recommendation for Documentation= fields in unit files to the policy

Reported by: lennart Owned by: spot
Priority: minor Milestone:
Component: Guideline Draft Version:
Keywords: Cc:
Blocked By: Blocking:

Description

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

Change History

comment:1 follow-up: ↓ 2 Changed 22 months ago by 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.

comment:2 in reply to: ↑ 1 Changed 22 months ago by lennart

Replying to 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?"

comment:3 follow-up: ↓ 4 Changed 22 months ago by spot

  • Status changed from new to assigned
  • Owner set to 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)."

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.

comment:4 in reply to: ↑ 3 ; follow-up: ↓ 5 Changed 21 months ago by lennart

Replying to 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.

comment:5 in reply to: ↑ 4 Changed 21 months ago by lennart

Replying to 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.

comment:6 Changed 21 months ago by spot

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)

comment:7 Changed 21 months ago by spot

  • Resolution set to fixed
  • Status changed from assigned to closed

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

comment:8 Changed 21 months ago by lennart

Thanks!

Note: See TracTickets for help on using tickets.