From 5b5ca99e3c94e40d67acb60f1d567d92e5609b8a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Feb 2023 22:50:57 +0000 Subject: [PATCH 1/4] spec: Fix a trailing comma at the end of a paragraph Signed-off-by: Philip Withnall --- docs/xml/releases-data.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/xml/releases-data.xml b/docs/xml/releases-data.xml index 0cd30b4c..243709d3 100644 --- a/docs/xml/releases-data.xml +++ b/docs/xml/releases-data.xml @@ -162,7 +162,7 @@ The issues tag contains issue children defining issues resolved by this release. - It is used most commonly to mention CVE IDs, + It is used most commonly to mention CVE IDs. The value of an issue tag must be the bug number, ticket name, or CVE ID and is typically displayed to the user, but may also in case of CVE IDs be read by From 565bace1c862971199fa60fde1529daef095a9cb Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Feb 2023 23:21:37 +0000 Subject: [PATCH 2/4] spec: Expand documentation for elements 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 Fixes: #458 --- docs/xml/releases-data.xml | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/xml/releases-data.xml b/docs/xml/releases-data.xml index 243709d3..212a6629 100644 --- a/docs/xml/releases-data.xml +++ b/docs/xml/releases-data.xml @@ -167,10 +167,35 @@ The value of an issue tag must be the bug number, ticket name, or CVE ID and is typically displayed to the user, but may also in case of CVE IDs be read by machines. The content of an issue element is not translatable, but can be a string appropriate for the project's bug tracker. - If the element's value is a CVE ID, the type property of the issue tag must be set to cve. - If the type property is missing, an issue type of generic is assumed. The url property can be used to provide - a web URL to a details page on the respective issue. It is required for all issue types, except for the cve type, where it is optional. + + The issue tag may have a type property, which should have a value of generic or cve. + If the type property is missing, a type of generic is assumed. + + + It may also have a url property, which should be a URL for a details page on the respective issue. + + + If type is cve, the element’s value must be a CVE ID in the format defined by MITRE. + For example, CVE-2023-12345. Software consuming the release data of a component should be able to append the element’s value to https://nvd.nist.gov/vuln/detail/ to get a page of information about the CVE. + If a url property is given, its value overrides any URL constructed from the CVE identifier. + The url property is optional if type is cve. + + + For example: + + bz#12345]]> + + If type is generic or unspecified, the element’s value is a free-form issue identifier, and the url property must be specified. + The issue identifier should be shorthand for an issue in the project’s bug tracker, and it does not have to be globally unique. It should be human readable, but does not have to be appropriate for non-technical audiences. + + + For example: + + + CVE-2021-28153 + CVE-2021-27218 +]]> From a1d3fd13369257f3ca7d22041e2465fc0ba5435c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Feb 2023 23:30:04 +0000 Subject: [PATCH 3/4] spec: Mention that is not part of the description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Given that it’s typically written right after the `` 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 Helps: #458 --- docs/xml/releases-data.xml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/xml/releases-data.xml b/docs/xml/releases-data.xml index 212a6629..6b46eec5 100644 --- a/docs/xml/releases-data.xml +++ b/docs/xml/releases-data.xml @@ -163,6 +163,7 @@ The issues tag contains issue children defining issues resolved by this release. It is used most commonly to mention CVE IDs. + Software which is interpreting the release notes for the component should present the list of issues separately from the release description. They should not be thought of as a bullet-point list of issues which follow straight on in prose from the description element’s value. The value of an issue tag must be the bug number, ticket name, or CVE ID and is typically displayed to the user, but may also in case of CVE IDs be read by From 531dd14363f18fdce3442dcbd7c816bbcdae42a9 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Feb 2023 23:39:22 +0000 Subject: [PATCH 4/4] spec: Give some guidance about tone in release descriptions Signed-off-by: Philip Withnall Helps: #458 --- docs/xml/releases-data.xml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/xml/releases-data.xml b/docs/xml/releases-data.xml index 6b46eec5..afc0b0c7 100644 --- a/docs/xml/releases-data.xml +++ b/docs/xml/releases-data.xml @@ -140,7 +140,12 @@ A description tag contains a brief description of what is new in the release. - The description tag is structured as described in . + The intended audience of the description are the users of the component (who are typically not developers), and so the description should mention only the user visible changes in the release. + The description tag supports child tags as described in . + + + It is recommended to not link to issue trackers or bug reports, as these typically make no sense to users. + If particular issues need to be highlighted (for example, CVEs fixed in this release), they should be listed in the issues tag.