spec: Expand documentation for <issue> elements #463
Conversation
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Try and make it a bit clearer what formats are expected, and when URLs are expected to be given. What was there before was not incorrect, but was a bit hard to unpack. Add a couple more examples inline. Signed-off-by: Philip Withnall <pwithnall@endlessos.org> Fixes: ximion#458
Given that it’s typically written right after the `<description>` element, there’s a temptation to think that it will be presented right after the prose in the description. But that’s not necessarily the case. Signed-off-by: Philip Withnall <pwithnall@endlessos.org> Helps: ximion#458
Signed-off-by: Philip Withnall <pwithnall@endlessos.org> Helps: ximion#458
| <para> | ||
| If <literal>type</literal> is <literal>cve</literal>, the element’s value must be a CVE ID in the <ulink url="https://www.cve.org/About/Process#cve-id">format defined by MITRE</ulink>. | ||
| For example, <literal>CVE-2023-12345</literal>. Software consuming the release data of a component should be able to append the element’s value to <literal>https://nvd.nist.gov/vuln/detail/</literal> to get a page of information about the CVE. | ||
| If a <literal>url</literal> property is given, its value overrides any URL constructed from the CVE identifier. |
There was a problem hiding this comment.
I was going to say that this is probably wrong, but checked the implementation, and this is indeed how the implementation behaves. Neat! :-P
|
I was wondering whether this is a bit verbose, given that the specification is supposed to be brief and to the point, while we have the Quickstart Guide (that should actually be updated to fir the current age...) to be a lot more verbose with a ton more examples. However, the changes here are still not overly verbose and definitely improve the clarity of the specification. Also, more examples are always very useful!
Don't worry, the CI does that for you - but you could also just fetch DAPS from Git and even run it from Git. I think there's also an unofficial Fedora package: https://github.com/openSUSE/daps/blob/main/INSTALL.adoc |
See the commit messages.
This should hopefully resolve #458, although there may be things I’ve missed or have worded badly.
I also haven’t been able to preview the generated HTML, because I don’t have
dapsinstalled and from some quick searching around I can’t find it packaged for Fedora. I have run my changes throughxmllintat least.Closes #458