PR#1041: Use only .metainfo.xml in AppData guidelines - packaging-committee

packaging-committee

#1041 Use only .metainfo.xml in AppData guidelines

Merged 3 years ago by james. Opened 3 years ago by oturpe.

oturpe/packaging-committee appdata-update into master

Prefer .metainfo.xml in AppData guidelines

Otto Urpelainen • 3 years ago

9e32bf6

guidelines/modules/ROOT/examples/addon.metainfo.xml ~~guidelines/modules/ROOT/examples/metainfo.xml~~

file renamed

file was moved with no change to the file

guidelines/modules/ROOT/examples/app.metainfo.xml ~~guidelines/modules/ROOT/examples/appdata.xml~~

file renamed

file was moved with no change to the file

guidelines/modules/ROOT/pages/AppData.adoc

file modified

+23 -27

		`@@ -1,15 +1,15 @@`
		`= Packaging Guidelines for AppData Files`
		`- :last-reviewed: 2019-01-17`
		`+ :last-reviewed: 2021-01-18`
		`:toc:`

		`If a package contains a GUI application,`
		- then it SHOULD install a `+.appdata.xml+` file
		+ then it SHOULD install a `+.metainfo.xml+` file
		into `+%{_metainfodir}+`.
		- Installed `+.appdata.xml+` files MUST follow
		`- the http://people.freedesktop.org/~hughsient/appdata/[AppData specification page].`
		+ Installed `+.metainfo.xml+` files MUST follow
		`+ the https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html#sect-Quickstart-DesktopApps[AppStream specification page].`

		`If a package contains an add-on for GUI application,`
		- then it SHOULD also install a `+.metainfo.xml+` file
		+ then it SHOULD install a `+.metainfo.xml+` file
		into `+%{_metainfodir}+`.
		Installed `+.metainfo.xml+` files MUST follow
		`the http://www.freedesktop.org/software/appstream/docs/sect-Quickstart-Addons.html[AppStream add-ons specification].`
		`@@ -17,10 +17,15 @@`
		`The AppData files MUST correctly validate using`
		`+appstream-util validate-relax+`.

		`- == .appdata.xml file creation`
		`+ .appdata.xml files`
		`+ NOTE: For historical reasons, AppStream specification also allows using`
		+ extension `+.appdata.xml+` for GUI applications. If upstream provides metadata
		+ with `+.appdata.xml+` extension, it MAY be used instead of `+.metainfo.xml+`.
		`+`
		`+ == .metainfo.xml file creation`

		`If the package doesn't already include and install`
		- its own `+.appdata.xml+` file,
		+ its own `+.metainfo.xml+` file,
		`you can make your own and send it upstream.`
		`Some benefits of sending the file upstream are that`
		`upstream can translate the file using`
		`@@ -28,36 +33,28 @@`
		`and can also modify the screenshots and descriptions`
		`as the application changes over time.`

		- You may include an `+.appdata.xml+` file you create
		- as a Source: (e.g. `+Source3: %{name}.appdata.xml+`)
		+ You may include an `+.metainfo.xml+` file you create
		+ as a Source: (e.g. `+Source3: %{name}.metainfo.xml+`)
		`or generate it in the spec file.`

		- Here is the contents of a sample `+.appdata.xml+` file
		`- (comical.appdata.xml):`
		+ Here are the contents of a sample application `+.metainfo.xml+` file
		`+ (comical.metainfo.xml):`

		`[source,xml]`
		`----`
		`- include::{examplesdir}/appdata.xml[]`
		`+ include::{examplesdir}/app.metainfo.xml[]`
		`----`

		`- The AppData file MUST be named with the same root as the .desktop file,`
		`+ Application's AppData file MUST be named with the same root as the .desktop file,`
		so if the .desktop file is named `+org.gnome.SomeApp.desktop+`
		- then the AppData file MUST be called `+org.gnome.SomeApp.appdata.xml+`.
		+ then the AppData file MUST be called `+org.gnome.SomeApp.metainfo.xml+`.

		`- == .metainfo.xml file creation`
		`-`
		`- If the add-on package doesn't already include and install`
		- its own `+.metainfo.xml+` file,
		`- you can make your own and send it upstream.`
		- You can do this by including a `+.metainfo.xml+` file you create
		- as a Source: (e.g. `+Source4: %{name}.metainfo.xml+`)
		`- or generating it in the spec file.`
		- Here is the contents of a sample `+.metainfo.xml+` file
		+ Here are the contents of a sample addon `+.metainfo.xml+` file
		`(gedit-bookmarks.metainfo.xml):`

		`[source,xml]`
		`....`
		`- include::{examplesdir}/metainfo.xml[]`
		`+ include::{examplesdir}/addon.metainfo.xml[]`
		`....`

		You can use anything as the `+<id>+`
		`@@ -66,8 +63,7 @@`

		`== app-data-validate usage`

		`- Although you can just include the .appdata.xml`
		`- or .metainfo.xml files in the package,`
		`+ Although you can just include the .metainfo.xml file in the package,`
		you MUST run `+appstream-util validate-relax+`
		(in `+%check+` or `+%install+`)
		and have `+BuildRequires: libappstream-glib+`,
		`@@ -76,5 +72,5 @@`
		`An example:`

		`....`
		`- appstream-util validate-relax --nonet %{buildroot}%{_metainfodir}/*.appdata.xml`
		`+ appstream-util validate-relax --nonet %{buildroot}%{_metainfodir}/*.metainfo.xml`
		`....`

oturpe commented 3 years ago

Current AppStream documentation instructs saving all AppStream metainfo with file extension metainfo.xml and mentions appdata.xml only as historical (though supported) format. Since metainfo.xml is now preferred, Fedora should use it for all AppData.

Using only metainfo.xml extension also makes the guidelines somewhat simpler, since less duplication is needed to cover two file extensions.

Relevant discussion:
1. https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/HYLVPAHS5WS5QZIDLTAXLT3XFH6SUBS2/
2. https://pagure.io/packaging-committee/issue/944
3. https://lists.fedoraproject.org/archives/list/packaging@lists.fedoraproject.org/thread/TPJPRPTGXNPK3R3BYGDVF3H3UNOR45J2/

decathorpe commented 3 years ago

I'm not sure if only mentioning metainfo.xml file extension is a good idea, since almost all upstream projects still use appdata.xml. This might lead to the (wrong) impression that packages have to rename those files (which they do not).

rebased onto e708aff16d49ec5929b2c6749a9a8b7fa69b6a69

3 years ago

oturpe commented 3 years ago

That is a valid concern. I added a new paragraph to cover that situation:

For GUI applications, extension +.appdata.xml+ MAY be used instead of
+.metainfo.xml+ if upstream provides an AppData file named so.

Does that address your concern?

Edited 3 years ago by oturpe

vondruch commented 3 years ago

Wouldn't it be better to extract it into NOTE: *.appdata.xml*: and describe it as obsolete practice? That way, it would send a message to package maintainers that they should collaborate with upstream to update the AppData to the latest specification.

Edited 3 years ago by vondruch

rebased onto 9e32bf6

3 years ago

oturpe commented 3 years ago

Another good suggestion. I moved the appdata.xml discussion into a note.

I did not add explicit suggestion to submit an update upstream, and used milder terminology than "obsolete practice", since a) I read @decathorpe 's comment as supporting not actively directing resources in renaming existing metadata files and b) AppStream also uses quite mild wording for this ("supported for historical reasons", compare with "deprecated and may be removed in a future release" they use for the appdata directory). The note can be rephrased if different tone is desired.