Add AppStream metadata file
ClosedPublic

Authored by ngraham on Aug 20 2019, 7:32 PM.

Details

Summary

Alternative to D23302. According to the AppStream documentation (https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Application.html),
adding an AppStream metadata file with multiple launchable tags will prevent AppStream
info generators from parsing desktop files to determine metadata, which sbhould solve
the problem of System Settings showing up twice in Discover and other software centers
due to how it installs more than one .desktop file.

Test Plan

Cannot test AppStream changes, but appstreamcli validate passes, and upon being compiled and installed, the file is located in the right place.

Diff Detail

Repository
R124 System Settings
Branch
add-appdata-file (branched from master)
Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 15414
Build 15432: arc lint + arc unit
ngraham created this revision.Aug 20 2019, 7:32 PM
Restricted Application added a project: Plasma. · View Herald TranscriptAug 20 2019, 7:32 PM
Restricted Application added a subscriber: plasma-devel. · View Herald Transcript
ngraham requested review of this revision.Aug 20 2019, 7:32 PM
ngraham edited the test plan for this revision. (Show Details)
ngraham edited the test plan for this revision. (Show Details)Aug 20 2019, 7:38 PM
mak added a comment.Aug 20 2019, 7:58 PM

@ngraham

Alternative to D23302. According to the AppStream documentation (https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Application.html),
adding an AppStream metadata file with multiple launchable tags will prevent AppStream
info generators from parsing desktop files to determine metadata,

I don't think this will do what you intend. What will actually happen here is that an AppStream generator will not *merge* in data from any of the desktop files into the final metadata collection, only being limited to what is in the .desktop file. Having the two launchable tags though will make software centers ask the user which app they want to launch if they click on the "Launch" button in a software center, which in this case are both identical.

If you just want to hide a .desktop file from being processed by AppStream, there is a much simpler solution: Just add X-AppStream-Ignore=true to the .desktop file in question, and it will be hidden (unless it is referenced in a metainfo file of course, in which case it may still be used as data source for that metainfo file).

mak added a comment.EditedAug 20 2019, 8:02 PM

There's also a FAQ entry for this, apparently I only documented this for Debian Developers back in the day ^^
--> https://wiki.debian.org/AppStream/Guidelines#How_to_exclude_.desktop_files_from_the_metadata

We may actually be at a point where we could only process stuff that has metainfo files by default in appstream-generator now... Something to consider for future releases.

ngraham updated this revision to Diff 64168.Aug 20 2019, 8:02 PM

Adjust according to review comments

Thanks for the into @mak, that's very helpful. I've removed one of the launchable tags since only one .desktop file has the info that you would want to use to launch it as a KDE user. And I've added X-AppStream-Ignore=true to one of the .desktop files.

Does this look correct now?

ngraham updated this revision to Diff 64169.Aug 20 2019, 8:06 PM

Add <provides> tag so searching for it from the old URLs still works

@mak: tnanks for the hint. will also see to use X-AppStream-Ignore for kdevelop then. any chance we can see this trick documented on https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Application.html , please? :)

mak added a comment.Aug 20 2019, 8:12 PM

Adjust according to review comments

This will work. I would change <name>System Settings</name> to <name> KDE System Settings</name> or <name>Plasma System Settings</name>, just like GNOME sets a name like "GNOME Videos" instead of "Videos" in their metadata. Otherwise this name will confuse users of GNOME, I guess.
You'll also highly likely want to set compulsory_for_desktop ( https://www.freedesktop.org/software/appstream/docs/chap-CollectionData.html#tag-ct-compulsory_for_desktop ) to prevent this app to be removable on Plasma.
So adding

<compulsory_for_desktop>KDE</compulsory_for_desktop>
<compulsory_for_desktop>Plasma</compulsory_for_desktop>

will do the trick (AppStream recognizes "Plasma", but the desktop is actually known as "KDE" everywhere in Freedesktop, so just using "KDE" would probably be sufficient and compatible with everything. Having "Plasma" as well won't hurt though)
Ypu may want FSFAP as metadata_license as it's much shorter than CC0 and mixes well with GPL. However that's a personal choice and not required for anything. CC0 would work just fine.

mak added a comment.Aug 20 2019, 8:13 PM

@mak: tnanks for the hint. will also see to use X-AppStream-Ignore for kdevelop then. any chance we can see this trick documented on https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Application.html , please? :)

There should probably be another note block on that page... ;-)

In D23306#515589, @mak wrote:

Adjust according to review comments

This will work. I would change <name>System Settings</name> to <name> KDE System Settings</name> or <name>Plasma System Settings</name>, just like GNOME sets a name like "GNOME Videos" instead of "Videos" in their metadata. Otherwise this name will confuse users of GNOME, I guess.

This gets at the original reason why System Settings has two .desktop files: one adds "KDE" onto the beginning of the name when it's not run in Plasma. Ideally we would want the same thing in AppStream:

  • Show "KDE Plasma System Settings" in search and browse lists, where the fact that it's for KDE Plasma is otherwise not apparent
  • Show "System Settings" in Discover's Updates lists, where the fact that it's for KDE Plasma is implied and redundant because you're seeing it in Plasma's software updater

Is such a thing possible?

You'll also highly likely want to set compulsory_for_desktop ( https://www.freedesktop.org/software/appstream/docs/chap-CollectionData.html#tag-ct-compulsory_for_desktop ) to prevent this app to be removable on Plasma.
So adding

<compulsory_for_desktop>KDE</compulsory_for_desktop>
<compulsory_for_desktop>Plasma</compulsory_for_desktop>

will do the trick (AppStream recognizes "Plasma", but the desktop is actually known as "KDE" everywhere in Freedesktop, so just using "KDE" would probably be sufficient and compatible with everything. Having "Plasma" as well won't hurt though)
Ypu may want FSFAP as metadata_license as it's much shorter than CC0 and mixes well with GPL. However that's a personal choice and not required for anything. CC0 would work just fine.

Thanks, will do.

mak added a comment.Aug 20 2019, 8:25 PM
In D23306#515589, @mak wrote:

Adjust according to review comments

This will work. I would change <name>System Settings</name> to <name> KDE System Settings</name> or <name>Plasma System Settings</name>, just like GNOME sets a name like "GNOME Videos" instead of "Videos" in their metadata. Otherwise this name will confuse users of GNOME, I guess.

This gets at the original reason why System Settings has two .desktop files: one adds "KDE" onto the beginning of the name when it's not run in Plasma. Ideally we would want the same thing in AppStream:

  • Show "KDE Plasma System Settings" in search and browse lists, where the fact that it's for KDE Plasma is otherwise not apparent
  • Show "System Settings" in Discover's Updates lists, where the fact that it's for KDE Plasma is implied and redundant because you're seeing it in Plasma's software updater

    Is such a thing possible?

Not at the moment... Discover can use the compulsory information to group the components into a "System components" group and it could also use the AppStream ID to arbitrarily override component names.
The AppStream metainfo data is intended to be completely desktop agnostic and reliably the same on every software center, that's why we don't allow apps to change names depending on which software center they are in.
However, software centers may use the compulsory information to actually completely hide components from foreign desktops, so not having a KDE prefix may not even be necessary. I am not sure if GNOME Software actually hides the apps based on the compulsory information (as this may also cause problems, e.g. I would consider Dolphin to be compulsory for Plasma, but GNOME people may potentially also want to install that file manager, so hiding it in GNOME Software may actually be wrong here).

In fact there are three possible relationships:

  • App is associated with desktop, but not required by it or limited to it (e.g. Dolphin, Gwenview, Nautilus, GNOME Music)
  • App requires desktop (e.g. KDE System Settings, GNOME System Settings, GNOME Tweaks)
  • Desktop requires app (e.g. KDE System Settings, GNOME System Settings)

If we had the ability to mark things according to the above relationships that would be amazing.

mak added a comment.Aug 20 2019, 8:50 PM

In fact there are three possible relationships:

  • App is associated with desktop, but not required by it or limited to it (e.g. Dolphin, Gwenview, Nautilus, GNOME Music)

--> project_group https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-project_group

  • App requires desktop (e.g. KDE System Settings, GNOME System Settings, GNOME Tweaks)

--> compulsory_for_desktop https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-compulsory_for_desktop
(Also potentially extends, if the thing in question is an addon / desktop-shell extension)

  • Desktop requires app (e.g. KDE System Settings, GNOME System Settings)

--> compulsory_for_desktop https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-compulsory_for_desktop

If we had the ability to mark things according to the above relationships that would be amazing.

We actually can, I think...

@kossebau How to hide .desktop files from AppStream is now more visible in https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Application.html#spec-appdata-introduction as a hint.

In D23306#515609, @mak wrote:

Thanks! Though reading it, leaves open questions with me:

  • what is meant by "referenced"? only via <launchable>?
  • if there are two desktop files referenced by <launchable> where one has the ignore entry set, will this overrule the "Data will only be fetched from a desktop file if one <launchable/> tag is present" rules above?
ngraham updated this revision to Diff 64171.Aug 20 2019, 9:21 PM

Add project_group and compulsory_for_desktop tags

mak added a comment.Aug 20 2019, 10:00 PM
In D23306#515609, @mak wrote:

Thanks! Though reading it, leaves open questions with me:

  • what is meant by "referenced"? only via <launchable>?

In modern metainfo files yes, only via launchable. However, if a component id has a .desktop suffix, as was required in the past, and a matching .desktop file is found, that also counts as referenced and the desktop-entry file will be read.

  • if there are two desktop files referenced by <launchable> where one has the ignore entry set, will this overrule the "Data will only be fetched from a desktop file if one <launchable/> tag is present" rules above?

No. A launchable tag always beats whatever was defined in the desktop-entry file itself, so if there is one launchable tag, the .desktop entry file will be taken into consideration no matter what was defined in it (to e.g. merge in category information). Any equivalent data in the metainfo file beats that of the desktop-entry file though. If there are multiple launchable entries, the generator has no idea which .desktop file to read, so rather than reading any and getting information wrong, it will read none (requiring the metainfo author to add all data they want in there explicitly).
This could maybe be made smarter, but tbh this case is so rare that just making the metainfo files more complete in such events seems like the better approach.

Hmm, it works fine here - maybe refresh the page? (the page was recently updated and your browser may still have an older, cached version)

In D23306#515662, @mak wrote:

Thanks! Though reading it, leaves open questions with me:

  • what is meant by "referenced"? only via <launchable>?

In modern metainfo files yes, only via launchable. However, if a component id has a .desktop suffix, as was required in the past, and a matching .desktop file is found, that also counts as referenced and the desktop-entry file will be read.

As developer trying to write metainfo files, I would welcome this logic also documented n the docs. The current content of the docs is confusing to me at least.

  • if there are two desktop files referenced by <launchable> where one has the ignore entry set, will this overrule the "Data will only be fetched from a desktop file if one <launchable/> tag is present" rules above?

No. A launchable tag always beats whatever was defined in the desktop-entry file itself, so if there is one launchable tag, the .desktop entry file will be taken into consideration no matter what was defined in it (to e.g. merge in category information). Any equivalent data in the metainfo file beats that of the desktop-entry file though. If there are multiple launchable entries, the generator has no idea which .desktop file to read, so rather than reading any and getting information wrong, it will read none (requiring the metainfo author to add all data they want in there explicitly).
This could maybe be made smarter, but tbh this case is so rare that just making the metainfo files more complete in such events seems like the better approach.

So, in our case here, <launchable type="desktop-id">systemsettings.desktop</launchable> actually means there is no need to add X-AppStream-Ignore=true to "kdesystemsettings.desktop" ? Because the generators would ignore it already due to a <launchable> present and pointing to the other desktop file?

apol accepted this revision.Aug 21 2019, 2:57 PM
This revision is now accepted and ready to land.Aug 21 2019, 2:57 PM
kossebau added inline comments.Aug 21 2019, 3:08 PM
app/kdesystemsettings.desktop
163 ↗(On Diff #64171)

For what I understood from "No. A launchable tag always beats whatever was defined in the desktop-entry file itself, so if there is one launchable tag, the .desktop entry file will be taken into consideration no matter what was defined in it (to e.g. merge in category information). If there are multiple launchable entries, the generator has no idea which .desktop file to read, so rather than reading any and getting information wrong, it will read none (requiring the metainfo author to add all data they want in there explicitly)." this is not needed here or rather without effect, given there the appdata file has one <launchable> entry pointing to the other desktop file.

ngraham updated this revision to Diff 64221.Aug 21 2019, 3:16 PM
ngraham marked an inline comment as done.

Remove unnecessary X-AppStream-Ignore property

This revision was automatically updated to reflect the committed changes.

Hi @mak, so seems we appdata content creators are still unsure what to do, allow me to put the last question of last night again to your attention:

In D23306#515662, @mak wrote:
  • if there are two desktop files referenced by <launchable> where one has the ignore entry set, will this overrule the "Data will only be fetched from a desktop file if one <launchable/> tag is present" rules above?

No. A launchable tag always beats whatever was defined in the desktop-entry file itself, so if there is one launchable tag, the .desktop entry file will be taken into consideration no matter what was defined in it (to e.g. merge in category information). Any equivalent data in the metainfo file beats that of the desktop-entry file though. If there are multiple launchable entries, the generator has no idea which .desktop file to read, so rather than reading any and getting information wrong, it will read none (requiring the metainfo author to add all data they want in there explicitly).
This could maybe be made smarter, but tbh this case is so rare that just making the metainfo files more complete in such events seems like the better approach.

So, in our case here, <launchable type="desktop-id">systemsettings.desktop</launchable> actually means there is no need to add X-AppStream-Ignore=true to "kdesystemsettings.desktop" ? Because the generators would ignore it already due to a <launchable> present and pointing to the other desktop file?

@ngraham You used the "appdata.xml" file suffix here. I noticed yesterday when reading the spec that it now declares that as legacy suffix:

While desktop-application metadata is commonly stored in /usr/share/metainfo/%{id}.metainfo.xml (with a .metainfo.xml extension), using a .appdata.xml extension is also permitted for this component type for legacy compatibility.

From https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Application.html

Given Plasma targets newer system, perhaps it makes sense to start right away with a metainfo.xml suffix?

@ngraham You used the "appdata.xml" file suffix here. I noticed yesterday when reading the spec that it now declares that as legacy suffix:

While desktop-application metadata is commonly stored in /usr/share/metainfo/%{id}.metainfo.xml (with a .metainfo.xml extension), using a .appdata.xml extension is also permitted for this component type for legacy compatibility.

From https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Application.html

Given Plasma targets newer system, perhaps it makes sense to start right away with a metainfo.xml suffix?

Sounds good. See D23325

mak added a comment.Aug 21 2019, 6:43 PM
In D23306#515662, @mak wrote:

Thanks! Though reading it, leaves open questions with me:

  • what is meant by "referenced"? only via <launchable>?

In modern metainfo files yes, only via launchable. However, if a component id has a .desktop suffix, as was required in the past, and a matching .desktop file is found, that also counts as referenced and the desktop-entry file will be read.

As developer trying to write metainfo files, I would welcome this logic also documented n the docs. The current content of the docs is confusing to me at least.

  • if there are two desktop files referenced by <launchable> where one has the ignore entry set, will this overrule the "Data will only be fetched from a desktop file if one <launchable/> tag is present" rules above?

No. A launchable tag always beats whatever was defined in the desktop-entry file itself, so if there is one launchable tag, the .desktop entry file will be taken into consideration no matter what was defined in it (to e.g. merge in category information). Any equivalent data in the metainfo file beats that of the desktop-entry file though. If there are multiple launchable entries, the generator has no idea which .desktop file to read, so rather than reading any and getting information wrong, it will read none (requiring the metainfo author to add all data they want in there explicitly).
This could maybe be made smarter, but tbh this case is so rare that just making the metainfo files more complete in such events seems like the better approach.

So, in our case here, <launchable type="desktop-id">systemsettings.desktop</launchable> actually means there is no need to add X-AppStream-Ignore=true to "kdesystemsettings.desktop" ? Because the generators would ignore it already due to a <launchable> present and pointing to the other desktop file?

No, you need X-AppStream-Ignore=true in kdesystemsettings.desktop, because since the desktop filename is different, the AppStream generator will see those as different applications and create entries for both. You however do not need to add the AppStream-ignore field to the systemsettings.desktop file, as that one is referenced from the metainfo file and therefore the metadata generator will know that the two files belong together and describe just one application. (if there was another launchable entry for kdesystemsettings.desktop, that would also be the case, but it would break the "Launch" dialog in software centers, so having one .desktop file ignored is the way to go)

All right, hopefully the third time's the charm: D23328