If your app contains Appstream metadata file ( eg. org.gnome.X.appdata.xml )

[Sid]

Hi,

TL;DR:

If your app is listed in https://appstream.debian.org/sid/main/issues/index.html, it means your appdata file might have issues.

Click your app in the above page

-or-

Run the following command.

$ appstreamcli validate --explain org.gnome.MyApp.appdata.xml

and fix warnings / errors etc.

Also, fix it in all older branches gnome-44 / gnome-43 etc as applicable.

Explanation:

While working with GNOME Software, I noticed that the version history / update history listed in the app often is missing release information for a particular release.

This happens due to 2 reasons:

Reason 1:

Upstream package maintainers haven’t added any description for the release notes in their Appdata file.

For example:

  <releases>
    <release version="42.beta" date="2022-03-04">
    <release version="40.0" date="2021-03-27">
    <release version="40.beta" date="2021-02-13">
  </releases>

The above XML release data will produce the following history in GNOME Software Version History Dialog, which is not very useful.

Solution:

Please do update your appdata files, with what minimal release information possible rather than leaving it empty.

Reason 2:

Upstream package maintainers “have” added all the necessary description for each release in the appdata file.

For example:

  <releases>
    <release version="42.beta" date="2022-03-04">
      <ul>
        <li>Fix GNOME Extensions link</li>
        <li>Clarify legacy GTK theme setting</li>
        <li>Remove tweaks duplicated in Settings</li>
        <li>Update translations</li>
      </ul>
    </release>
    <release version="40.0" date="2021-03-27">
      <p>
          First stable release for GNOME 40. This version is mainly comprised
          of bug fixes and changes for GNOME 40. There are also some notable
          improvements:
      </p>
      <ul>
        <li>Remove Extensions support (now found in the Extensions app)</li>
        <li>Support new font settings for GNOME 40</li>
        <li>Fix UI on small screens</li>
        <li>Update translations</li>
      </ul>
    </release>
    <release version="40.beta" date="2021-02-13">
      <ul>
        <li>Remove Extensions support</li>
        <li>Add Flatpak support</li>
        <li>Support new font settings</li>
        <li>Fix leaflet on small screens</li>
        <li>Various other bug fixes</li>
        <li>Update translations</li>
      </ul>
    </release>
  </releases>

But, still they see the same screenshot as shown above.

This is because this is not well formed Appstream XML metadata. Hence, it fails validation checks and the data within the invalid tags ( <release> ) are rejected by Appstream.

Solution:

Run the following command to validate your Appdata file and fix errors / warnings.

$ appstreamcli validate --explain org.gnome.MyApp.appdata.xml

E.g

$ appstreamcli validate _install/share/metainfo/org.gnome.tweaks.appdata.xml

I: org.gnome.tweaks:156: description-first-para-too-short
     GNOME Tweaks allows adjusting advanced GNOME options.
E: org.gnome.tweaks:252: release-description-outside-tag ul
E: org.gnome.tweaks:260: release-description-outside-tag p
E: org.gnome.tweaks:260: release-description-outside-tag ul
E: org.gnome.tweaks:273: release-description-outside-tag ul
I: org.gnome.tweaks:287: nonstandard-gnome-extension kudos
E: org.gnome.tweaks:~: desktop-app-launchable-missing
W: org.gnome.tweaks:~: releases-not-in-order 40.0 << 40.beta
I: org.gnome.tweaks:~: content-rating-missing

✘ Validation failed: errors: 5, warnings: 1, infos: 3, pedantic: 1

Note: --explain option produces more human readable explanation. I’ve skipped it as it produces more text.

After fixing the warnings, the version history is properly displayed in GNOME Software now.

Cheers!
Sid

[Sid]

Also, after verification from

$ appstreamcli validate --explain org.gnome.MyApp.appdata.xml

the following gnome-software command can be used to see how the appdata looks in gnome-software

$ gnome-software --show-metainfo org.gnome.MyApp.appdata.xml

Example:

$ gnome-software --show-metainfo /local/metainfo/org.gnome.tweaks.appdata.xml

displays the following gnome-software app details page.

where you can click Version History button to check your version history.

Cheers,
Sid

[Sid]

NEWS vs org.gnome.MyApp.appdata.xml :

It seems that some GNOME apps add their release notes to the NEWS file, rather than their Appdata XML files. NEWS files are good for non-desktop apps which do not have an Appdata file ( e.g. Glib / GTK ), but for desktop apps this might not be really required.

I do understand that NEWS file has its uses. One way to solve this issue is to generate entries for NEWS file from Appdata XML file during every release.

Reason:

GNOME Software relies on release notes and it greatly improves user experience when updating packages.

1. If an app doesn’t have release notes in its Appdata files ( or doesn’t have an AppData file ), GNOME Software uses PackageKit as a fallback to get release notes. PackageKit is the backend used by GNOME Software to perform various package operations ( install-pkg / update-pkg etc ). It requests PackageKitto get distribution specific release notes for that app.

   • For debian / ubuntu based systems, PackageKit uses the apt backend which returns the Debian Changelog ( which is rarely useful for a desktop app ) for the app.

   • For Fedora / Redhat / CentOS based systems, PackageKit uses the dnf backend which returns the information from the NEWS file for the app. This is a bit buggy though, as sometimes release information is not complete.

     I think both the above are in place for non-desktop packages.

2. Also, if there are any issues in the [1], it will need to be fixed in PackageKit which follows a different / less frequent release cycle than GNOME. If Appdata files are updated with appropriate release information, GNOME Software directly renders them via Appstream library ( which is quicker ), without depending on PackageKit.

Next Steps:

1. Moving forward can we update the Appdata files for desktop applications, rather than updating NEWS file. If needed we can use a script to update the NEWS file from Appdata file ( the reverse will be really cumbersome ) during each release.

2. Welcome suggestions from the release team on what is the best way to move forward to achieve the above, so all GNOME apps have consistent Appdata files. Maybe, use a wrapper around "appstreamcli validate" which adds addition GNOME specific validation criteria ( e.g. check for release notes in AppData file during each release. etc ) ?

Cheers!
Sid

[Sid]

• Welcome suggestions from the release team on what is the best way to move forward to achieve the above, so all GNOME apps have consistent Appdata files. Maybe, use a wrapper around "appstreamcli validate" which adds addition GNOME specific validation criteria ( e.g. check for release notes in AppData file during each release. etc ) ?

@mcatanzaro : can the release team offer some assistance on this ?