doc: Add "service" components and their launchables #115
Conversation
|
Out of interest, how do you see gnome-software display this type of component? |
I was thinking that it would ignore it. |
|
Works for me! :) |
docs/sources/metainfo/component.xml
Outdated
| </para> | ||
| <para> | ||
| If more than one <literal>launchable</literal> tag of type <literal>service</literal> is | ||
| present, a UI is expected to let the user manage all these services. Thus multiple |
There was a problem hiding this comment.
Nitpick: One excessive space here...
What does "manage" mean? Do you mean start? Do you mean start/restart/stop? What happens when the service is a "oneshot" unit? Maybe clarify that.
There was a problem hiding this comment.
Do we need to go into that much detail here? "Manage" should mean start/stop/restart/enable/disable/monitor, what ever the UI offers for a service.
There was a problem hiding this comment.
I usually try to be precise here, because in case someone wants to implement a UI for a new software center but doesn't have the specific knowledge about services, it's helpful to know what the spec expects from UIs.
It also helps in case someone looks at the spec at a later date and wonders what the intentions were for a specific feature.
Arguably this is a rather nit-picky case here, as in case of Unix services it's well established what you can do with them.
There was a problem hiding this comment.
We would describe the UI of the launcher here, not of the software center, no? (For example, for desktop apps, we would be describing the GNOME Shell, not GNOME Software.)
I have tried to reword this without referring to "the UI" at all.
docs/sources/metainfo/service.xml
Outdated
| the Operating Systems "init" facility, such as systemd. | ||
| </para> | ||
| <para> | ||
| A service component is any software that is started and supervised by |
docs/sources/metainfo/service.xml
Outdated
| the Operating Systems "init" facility, such as systemd. | ||
| </para> | ||
| <para> | ||
| The file described in this document is built upon the generic component metadata with fields specific for services (see <xref linkend="sect-Metadata-GenericComponent"/>). |
There was a problem hiding this comment.
Don't say "file" as AppStream metadata might not be retrieved as file, and this generally is a bit confusing.
Usually, we use "component" here. Additionally, I try to avoid using the term "document" to refer to the text people are reading, because since there are XML documents and YAML documents as well as two types of AppStream "documents" this is confusing.
So, I'd probably have written something like "The component described here is built upon...."
There was a problem hiding this comment.
Other component types also use the term "file". Maybe we can change them all in a separate PR?
"Component" sounds wrong; we don't describe the component itself, but the format for expressing meta data about it. So what about "component metadata format"?
There was a problem hiding this comment.
Other component types also use the term "file". Maybe we can change them all in a separate PR?+
Jup, I can do that later.
"Component" sounds wrong; we don't describe the component itself, but the format for expressing meta data about it. So what about "component metadata format"?
You are right, "component metadata format" is way better - I think just writing "metadata" is fine as well (slightly less verbose)
docs/sources/metainfo/service.xml
Outdated
| This tag is described in detail for generic components at <xref linkend="tag-provides"/>. | ||
| </para> | ||
| <para> | ||
| For services, at least one provided <code><service/></code> must be listed in this tag. |
There was a problem hiding this comment.
Should it? And if so, what does the service provided-item contain as value?
There was a problem hiding this comment.
Good point, we don't need to mandate a <launchable> entry. Removed.
| This tag is described in detail for generic components at <xref linkend="tag-launchable"/>. | ||
| </para> | ||
| <para> | ||
| At least one launchable element with type "service" must be present. |
There was a problem hiding this comment.
Make that "service" a <literal>service</literal>
There was a problem hiding this comment.
Not relevant anymore since the text has been removed.
I'd rather not. |
|
I have pushed a new commit with the fixes. Would you like me to squash them right away into the main commit? |
|
You can squash and force-push, if you want :-) (I replied to your replied on the inline comments) |
Okay, I'll do that! |
|
Looks good, thank you for your contribution! I found some tiny indentation issues, which I'll resolve in some other commit later. Also, the C implementation is missing, but that's trivial and I'll add it for the next release. :-) |
No description provided.