The appstream specification is too vague about how to write release notes

[mike-fabian]

https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Releases.html#tag-release-issues

The specification is quite vague about what can be written in the <description> and <issue> tags for a release.

Long ago I wrote long bulleted lists with links to the issues fixed into <description> but then appstreamcli --validate complained, it did not want me to use URLs in the description and I was not able to achieve a nice looking formatted result of the text either. If I remember correctly, list using ul/li did not work in <description>.

Therefore, I changed <description> to only contain a generic message like Bugs fixed and tried to put the detailed information
into the <issue> tags, for example like:

    <release version="2.19.7" date="2022-10-24" urgency="medium">
      <description>
        <p>Bug fixes and enhancements</p>
      </description>
      <url>https://github.com/mike-fabian/ibus-typing-booster/releases/tag/2.19.7</url>
      <issues>
        <issue url="https://github.com/mike-fabian/ibus-typing-booster/issues/395">
          github-issues#395: Avoid inline completion when OSK
          (on-screen-keyboard) is shown
        </issue>

But gnome-software does not display that at all, see:

https://gitlab.gnome.org/GNOME/gnome-software/-/issues/2049#note_1648786

The gnome-software developer Milan Crha and me both think that the specification does not say clearly what exactly to write into the <issue> tags. What I did above seems reasonable to me, but when reading the specification I am not sure whether it is OK like that.

Can you please clarify this?

[ximion]

The release description is really a freeform text, the same you get on GitHub - you can make it look like you want, for example:

    <release type="stable" version="0.15.5" date="2022-08-22T00:00:00Z">
      <description>
        <p>This release adds the following features:</p>
        <ul>
          <li>validator: Allow severity downgrade of releases-not-in-order for GNOME</li>
          <li>validator: Perform stricter integer validation</li>
          <li>validator: Check for url redefinitions</li>
          <li>Add convenience function that check if component is free by license and origin</li>
          ...
        </ul>
        <p>This release updates documentation:</p>
        <ul>
          <li>spec: Add an &lt;internet/&gt; kind to requires/recommends/supports</li>
          ...
        </ul>
        <p>This release fixes the following bugs:</p>
        <ul>
          <li>validator: Don't permit overriding the unknown root tag issue</li>
          <li>compose: Don't crash if metainfo file contains an invalid stock icon</li>
          <li>spdx: Fix possible crash when NULL is passed to is_free_license</li>
          ...
        </ul>
        <p>This release includes the following changes:</p>
        <ul>
          <li>Silence static analyzer false-positives based on GCC version</li>
          ...
        </ul>
        <p>With contributions from:</p>
        <p>JakobDev, Philip Withnall, Pino Toscano, Matthias Klumpp</p>
      </description>
    </release>

The issue tag is used wrong in your example, it is not a translatable freeform text. From https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Releases.html#tag-release-issues :

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.

It's best to simply give a short summary as to which bug was fixed in the release description, so users don't need to click on stuff. The url element of a release is supposed to be a link to a very detailed release info page, for example something like this: https://krita.org/en/krita-5-1-release-notes/

Software centers don't need to display issue tags, they're optional (but it's of course pretty nice if they are displayed).
The specification seems to mention all this, but if you have any change ideas to improve clarity of the text, patches are welcome!

[mike-fabian]

The url element of a release is supposed to be a link to a very detailed release info page,

I think my url element does this,

https://github.com/mike-fabian/ibus-typing-booster/releases/tag/2.19.7

gives detailed information about the release but it is not displayed by gnome-software.

[mike-fabian]

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.

Unfortunately it is not displayed to the user, and if it were, how should the bug number look like to indicate from what tracker the bug number is?
The URL has the full information about the tracker and the bug id already, but how encode this again in the text value of the issue tag? And why duplicate that bug number in the text when it is already in the URL?

[mike-fabian]

The release description is really a freeform text, the same you get on GitHub - you can make it look like you want, for example:

I used to have it like that, but I wanted to include URLs to the issues fixed and appstreamcli --validate complains when I add URL to the issues. For example this was not allowed:

<li>Some text describing the issue (Resolves: https://github.com/foo/bar/issues/4711)</li>

So I moved the URLs to <issue url="...">, then appstreamcli --validate does not complain.

But if I do

   <description>
     ...
   <li>Some text describing the issue (Resolves: https://github.com/foo/bar/issues/4711)</li>
   ...
   </description>
   ...
       <issue url="https://github.com/foo/bar/issues/4711">4711</issue>
   ...

then the issue url and the short describing text are somehow separated and one could not see quickly which issue this is, even if gnome-software displayed the contents of the <issue> tags at all, which it currently doesn't.

[ximion]

[my URL element] gives detailed information about the release but it is not displayed by gnome-software.

That is a bug in gnome-software, please file an issue with them!

The URL has the full information about the tracker and the bug id already, but how encode this again in the text value of the issue tag? And why duplicate that bug number in the text when it is already in the URL?

It will simply become a clickable link in the software center GUI, like LP: #1914868 or appstream: #1914868

Have a look at https://fwupd.org/lvfs/devices/com.fujitsu.LIFEBOOK.E5510-E5410.uefi.firmware for example as to how this may look like with CVE IDs (which is what this feature was originally designed for).

the issue url and the short describing text are somehow separated and one could not see quickly which issue this is, even if gnome-software displayed the contents of the <issue> tags at all, which it currently doesn't.

Yes, that's how it is right now - I'd just add the issue number to the text, and if you want to link it, add it as issue tag as well. Or don't link it and only link issues in the detailed report on the webpage you point to.
That GNOME Software doesn't display this is a thing you know, since you filed https://gitlab.gnome.org/GNOME/gnome-software/-/issues/2049 ;-) (and that's on GS, nothing we can do about it here).

Keep in mind that the <issue/> elements are not translatable and supposed to be machine-readable, it's a different purpose.

[pwithnall]

The URL has the full information about the tracker and the bug id already, but how encode this again in the text value of the issue tag? And why duplicate that bug number in the text when it is already in the URL?

It will simply become a clickable link in the software center GUI, like LP: #1914868 or appstream: #1914868

Have a look at https://fwupd.org/lvfs/devices/com.fujitsu.LIFEBOOK.E5510-E5410.uefi.firmware for example as to how this may look like with CVE IDs (which is what this feature was originally designed for).

From my point of view, the specification could benefit from including some examples of acceptable bug ID formats to use in <issue>. For example, should I use <issue>cve:1234</issue> or <issue>CVE: 1234</issue> or <issue>CVE-1234</issue>? What about <issue>gnome:gnome-software/1234</issue> or <issue>https://gitlab.gnome.org/GNOME/gnome-software/-/issues/1234</issue>?

We’re looking at implementing <issue> support in gnome-software, but there’s no way to link to the issues if their format is not precisely specified. 😁

[ximion]

From my point of view, the specification could benefit from including some examples of acceptable bug ID formats

Patches welcome ;-)
There are some examples in https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Releases.html#spec-releases-example though.
And for CVE-IDs, the format is set in stone by the specification: It must be a CVE-ID as described here and defined by MITRE Corporation (so, if you can attach it to the end of https://nvd.nist.gov/vuln/detail/ and get a valid website, you're good).
For url-type issues, you can use any text you like, we can't (and IMHO shouldn't) define precise naming for every bug tracking system under the sun.

[mike-fabian]

Thank you!