From Fedora Project Wiki
m (add note on License)
(make example file validate)
Line 7: Line 7:


=== .appdata.xml file creation ===
=== .appdata.xml file creation ===
If the package doesn't already include and install its own .appdata.xml file, you can make your own and sending it upstream. Benefits of sending the file upstream is that upstream can translate the file using the existing translation resources and can also modify the screenshots and descriptions as the application changes over time. If upstream is dead or unwilling you can do this downstream by including a .appdata.xml file you create as a Source: (e.g. Source3: %{name}.appdata.xml). Here is the contents of a sample .appdata.xml file (comical.appdata.xml):  
If the package doesn't already include and install its own .appdata.xml file, you can make your own and sending it upstream. Benefits of sending the file upstream is that upstream can translate the file using the existing translation resources and can also modify the screenshots and descriptions as the application changes over time. You can do this by including a .appdata.xml file you create as a Source: (e.g. Source3: %{name}.appdata.xml) or generating it in the spec file. Here is the contents of a sample .appdata.xml file (comical.appdata.xml):  


<pre>
<pre>
Line 13: Line 13:
<!-- Copyright 2014 Richard Hughes <richard@hughsie.com> -->
<!-- Copyright 2014 Richard Hughes <richard@hughsie.com> -->
<application>
<application>
   <id type="desktop">comical.appdata.xml</id>
   <id type="desktop">comical.desktop</id>
   <metadata_license>CC0</metadata_license>
   <metadata_license>CC0</metadata_license>
   <project_license>GPL-2.0+ and GFDL-1.3</project_license>
   <project_license>GPL-2.0+ and GFDL-1.3</project_license>
Line 20: Line 20:
   <description>
   <description>
     <p>
     <p>
       Comical is an easy to use and cross-platform CBR and CBZ reader.
       Comical is an easy to use and cross-platform CBR and CBZ reader which
      prefetches and caches pages for speed.
     </p>
     </p>
     <p>
     <p>
       ...lots of prose about the application...
       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!
     </p>
     </p>
   </description>
   </description>
   <screenshots>
   <screenshots>
     <screenshot type="default">http://comical.sourceforge.net/ss-1.png</screenshot>
     <screenshot type="default">http://comical.sourceforge.net/images/comical-0.5-linux.jpg</screenshot>
     <screenshot>http://comical.sourceforge.net/ss-2.png</screenshot>
     <screenshot>http://comical.sourceforge.net/images/comical-0.6-win32.jpg</screenshot>
   </screenshots>
   </screenshots>
   <url type="homepage">http://comical.sourceforge.net/</url>
   <url type="homepage">http://comical.sourceforge.net/</url>
Line 37: Line 39:
The AppData file MUST be named with the same root as the .desktop file, so if the .desktop file is named <code>org.gnome.SomeApp.desktop</code> then the AppData file MUST be called <code>org.gnome.SomeApp.appdata.xml</code>.
The AppData file MUST be named with the same root as the .desktop file, so if the .desktop file is named <code>org.gnome.SomeApp.desktop</code> then the AppData file MUST be called <code>org.gnome.SomeApp.appdata.xml</code>.


=== appdata-validate usage ===
=== desktop-file-install usage ===
Although you can just include the .appdata.xml file in the package, you SHOULD run  <code>appdata-validate</code> (in <code>%check</code> or <code>%install</code>) and have <code>BuildRequires: appdata-tools</code>, to help ensure .appdata.xml file safety and spec-compliance. Here are some examples of usage:
Although you can just include the .appdata.xml file in the package, you SHOULD run  <code>appdata-validate</code> (in <code>%check</code> or <code>%install</code>) and have <code>BuildRequires: appdata-tools</code>, to help ensure .appdata.xml file safety and spec-compliance. Here are some examples of usage:


Line 43: Line 45:
appdata-validate --nonet %{buildroot}/%{_datadir}/appdata/*.appdata.xml
appdata-validate --nonet %{buildroot}/%{_datadir}/appdata/*.appdata.xml
</pre>
</pre>
=== Licences of AppData files ===
AppData files can only be written in a small number of content licences (not including code licences like BSD or GPLv3+) and so if a new licence like CC0 is used for the AppData file then the spec file License value should be modified to include the AppData metadata_license value used.

Revision as of 11:53, 13 June 2014

AppData files

If a package contains a GUI application, then it SHOULD also include a properly installed .appdata.xml file. Installed .appdata.xml files MUST follow the AppData specification page, and they must correctly validate using appdata-validate.

.appdata.xml file creation

If the package doesn't already include and install its own .appdata.xml file, you can make your own and sending it upstream. Benefits of sending the file upstream is that upstream can translate the file using the existing translation resources and can also modify the screenshots and descriptions as the application changes over time. You can do this by including a .appdata.xml file you create as a Source: (e.g. Source3: %{name}.appdata.xml) or generating it in the spec file. Here is the contents of a sample .appdata.xml file (comical.appdata.xml): 

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright 2014 Richard Hughes <richard@hughsie.com> -->
<application>
  <id type="desktop">comical.desktop</id>
  <metadata_license>CC0</metadata_license>
  <project_license>GPL-2.0+ and GFDL-1.3</project_license>
  <name>Comical</name>
  <summary>A Comic Archive Reader</summary>
  <description>
    <p>
      Comical is an easy to use and cross-platform CBR and CBZ reader which
      prefetches and caches pages for speed.
    </p>
    <p>
      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! 
    </p>
  </description>
  <screenshots>
    <screenshot type="default">http://comical.sourceforge.net/images/comical-0.5-linux.jpg</screenshot>
    <screenshot>http://comical.sourceforge.net/images/comical-0.6-win32.jpg</screenshot>
  </screenshots>
  <url type="homepage">http://comical.sourceforge.net/</url>
  <updatecontact>richard_at_hughsie.com</updatecontact>
</application>

The 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.

desktop-file-install usage

Although you can just include the .appdata.xml file in the package, you SHOULD run appdata-validate (in %check or %install) and have BuildRequires: appdata-tools, to help ensure .appdata.xml file safety and spec-compliance. Here are some examples of usage: 

appdata-validate --nonet %{buildroot}/%{_datadir}/appdata/*.appdata.xml
Retrieved from "https://fedoraproject.org/w/index.php?title=User:Rhughes/DraftAppDataGuidelines&oldid=379769"