#1041 Use only .metainfo.xml in AppData guidelines
Merged a year ago by james. Opened a year ago by oturpe.
oturpe/packaging-committee appdata-update  into  master

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
@@ -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

  ....

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/

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

a year 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?

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.

rebased onto 9e32bf6

a year 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.

Commit d66c26a fixes this pull-request

Pull-Request has been merged by james

a year ago

Pull-Request has been merged by james

a year ago