From 9e32bf66b34e8f43af6ca07f00c181e57cf1b53c Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Jan 19 2021 16:23:51 +0000 Subject: Prefer .metainfo.xml in AppData guidelines Current AppStream documentation instructs saving all AppStream metainfo with file extension metainfo.xml and mentions appdata.xml 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. --- diff --git a/guidelines/modules/ROOT/examples/addon.metainfo.xml b/guidelines/modules/ROOT/examples/addon.metainfo.xml new file mode 100644 index 0000000..19d5d09 --- /dev/null +++ b/guidelines/modules/ROOT/examples/addon.metainfo.xml @@ -0,0 +1,11 @@ + + + gedit-bookmarks + gedit.desktop + Bookmarks + Easy document navigation with bookmarks + https://wiki.gnome.org/Apps/Gedit/ShippedPlugins + https://bugzilla.gnome.org/enter_bug.cgi?product=gedit&component=Plugins + CC0-1.0 + GPL-2.0+ + diff --git a/guidelines/modules/ROOT/examples/app.metainfo.xml b/guidelines/modules/ROOT/examples/app.metainfo.xml new file mode 100644 index 0000000..e285c08 --- /dev/null +++ b/guidelines/modules/ROOT/examples/app.metainfo.xml @@ -0,0 +1,38 @@ + + + + comical.desktop + CC0-1.0 + GPL-2.0+ and GFDL-1.3 + Comical + A Comic Archive Reader + Un Comic Archive Lecteur + +

+ Comical is an easy to use and cross-platform CBR and CBZ reader which + prefetches and caches pages for speed. +

+

+ Comical est une CBR et CBZ lecteur facile à utiliser et + multi-plateforme qui prélectures et caches pages pour la vitesse. +

+

+ Resized images are crisp, and you can view pages one or two at a time. + Comical is open-source, so feel free to contribute new features! +

+

+ Images redimensionnées sont nettes, et vous pouvez voir une ou deux pages à la fois. + Comical est open-source, alors n'hésitez pas à apporter de nouvelles fonctionnalités! +

+ + + + http://comical.sourceforge.net/images/comical-0.5-linux.jpg + + + http://comical.sourceforge.net/images/comical-0.6-win32.jpg + + + http://comical.sourceforge.net/ + richard_at_hughsie.com + diff --git a/guidelines/modules/ROOT/examples/appdata.xml b/guidelines/modules/ROOT/examples/appdata.xml deleted file mode 100644 index e285c08..0000000 --- a/guidelines/modules/ROOT/examples/appdata.xml +++ /dev/null @@ -1,38 +0,0 @@ - - - - comical.desktop - CC0-1.0 - GPL-2.0+ and GFDL-1.3 - Comical - A Comic Archive Reader - Un Comic Archive Lecteur - -

- Comical is an easy to use and cross-platform CBR and CBZ reader which - prefetches and caches pages for speed. -

-

- Comical est une CBR et CBZ lecteur facile à utiliser et - multi-plateforme qui prélectures et caches pages pour la vitesse. -

-

- Resized images are crisp, and you can view pages one or two at a time. - Comical is open-source, so feel free to contribute new features! -

-

- Images redimensionnées sont nettes, et vous pouvez voir une ou deux pages à la fois. - Comical est open-source, alors n'hésitez pas à apporter de nouvelles fonctionnalités! -

- - - - http://comical.sourceforge.net/images/comical-0.5-linux.jpg - - - http://comical.sourceforge.net/images/comical-0.6-win32.jpg - - - http://comical.sourceforge.net/ - richard_at_hughsie.com - diff --git a/guidelines/modules/ROOT/examples/metainfo.xml b/guidelines/modules/ROOT/examples/metainfo.xml deleted file mode 100644 index 19d5d09..0000000 --- a/guidelines/modules/ROOT/examples/metainfo.xml +++ /dev/null @@ -1,11 +0,0 @@ - - - gedit-bookmarks - gedit.desktop - Bookmarks - Easy document navigation with bookmarks - https://wiki.gnome.org/Apps/Gedit/ShippedPlugins - https://bugzilla.gnome.org/enter_bug.cgi?product=gedit&component=Plugins - CC0-1.0 - GPL-2.0+ - diff --git a/guidelines/modules/ROOT/pages/AppData.adoc b/guidelines/modules/ROOT/pages/AppData.adoc index 21b5ed8..8952c2f 100644 --- a/guidelines/modules/ROOT/pages/AppData.adoc +++ b/guidelines/modules/ROOT/pages/AppData.adoc @@ -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 http://www.freedesktop.org/software/appstream/docs/sect-Quickstart-Addons.ht 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 @@ the existing translation resources 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 `++` @@ -66,8 +63,7 @@ and also match the `+.metainfo.xml+` filename prefix. == 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 @@ of the appdata files you're installing. An example: .... -appstream-util validate-relax --nonet %{buildroot}%{_metainfodir}/*.appdata.xml +appstream-util validate-relax --nonet %{buildroot}%{_metainfodir}/*.metainfo.xml ....