GNOME Goal: AppData files for GNOME-Software
Guidelines
Every software center that exists allows the user to look at screenshots and a long description of the application before it is installed. For most users it allows them to answer the question Do I want to install this application?
Traditionally in Linux distributions, we have none of this data for the vast majority of our desktop user-installable applications. To solve this, we have defined a new data file, which the upstream project can optionally translate using the same technique as GSetting schemas or Desktop files. Rather than create a new schema from scratch, we'll be using a subset of the AppStream metadata proposal.
Applications wishing to have long descriptions, screenshots and other useful things are required to ship one or more files in /usr/share/appdata/%{id}.appdata.xml. In GNOME 3.14, we will only be showing applications that include AppData information, but until then it's optional but highly recommended.
|
Instructions on how to recognize a module affected by this goal.A module is affected by this goal if it ships a <app_id>.desktop file but doesn't ship a <app_id>.appdata.xml.in file. You can get more information about AppData file and how to create and distribute them at Richard Hughes' blog and the Official specification document. The specification document provides a lot of detail on the style of the description and describes all the tags in detail. You probably want to read it before starting to write an AppData file for a project.
If your desktop file is hidden, e.g. NoDisplay=true or if it does not have Type=Application, you do not need to create an AppData file as it will not show in the software center.
To apply this goal to an application, you should create a xml.in file with the following structure:
<?xml version="1.0" encoding="UTF-8"?> <component type="desktop"> <id>gnome-power-statistics.desktop</id> <!-- this is the licence of the appdata file, not the project. As specified in the SPDX OpenSource License Registry --> <licence>CC0-1.0</licence> <!-- Only include 'name' if you want the software center name to be different to the 'Name' in the .desktop file --> <name>Power Statistics</name> <!-- Only include 'summary' if you want the software center name to be different to the 'Comment' in the .desktop file --> <summary>Observe power management</summary> <description> <p> Power Statistics is a program used to view historical and current battery information and will show programs running on your computer using power. </p> <p>Example list:</p> <!-- try not to use lists unless you have to. Paragraphs look a lot better in nearly all cases --> <ul> <li>First item</li> <li>Second item</li> </ul> <p> You probably only need to install this application if you are having problems with your laptop battery, or are trying to work out what programs are using significant amounts of power. </p> </description> <screenshots> <screenshot type="default"> <image>http://www.hughsie.com/en_US/main.png</image> </screenshot> <screenshot> <image>http://www.hughsie.com/en_US/preferences.png</image> </screenshot> </screenshots> <url type="homepage">http://www.gnome.org/projects/en_US/gnome-power-manager</url> <!-- this is someone that wants to be notified when we add to the appdata specification --> <update_contact>gnome-power-manager-list@gnome.org</update_contact> </component>
If you want to mark a string for translation, use something like this (full patch):
<_p> Power Statistics is a program used to view historical and current battery information and will show programs running on your computer using power. </_p> <ul> <_li>First item</_li> <_li>Second item</_li> </ul>
A couple of common translation mistakes to avoid:
You need to distribute the .appdata.xml.in file, NOT the generated .appdata.xml, or out of tree builds will fail. dist_appdata_DATA in a Makefile.am is a mistake.
You want to use @INTLTOOL_XML_RULE@ to merge the translations into the generated .appdata.xml file. @INTLTOOL_XML_NOMERGE_RULE@ cannot be used and is no longer necessary for gsettings translations.
You should validate your .appdata.xml (after being generated from the .appdata.xml.in file) AppData file using the appstream-util validate tool available in appstream-glib. Files should validate with no warnings or errors. It is up to the maintainer if they want to validate the file in the build system, but if so, ensure to check for /usr/bin/appstream-util in the configure script also.
You should install the <id>.appdata.xml file to /usr/share/appdata/. This is to allow the software center to work in a limited way when the downstream distribution does not generate AppStream metadata from the AppData files.
Some applications we wanted to feature in 3.10 have already had AppData files written, and these are stored in a temporary location. If you copy a file from this repository ensure it's validated and translated before committing upstream. When the upstream project does a tarball release with the new AppData file the corresponding file will be automatically deleted in fedora-appstream if it exists. The files in fedora-appstream will also be cleared before 3.12, as the files are supposed to live, and be translated, upstream.
Comments before approval
|
Status of this goal
|
Patch Status |
Markup |
todo |
<: #ff8080> todo |
patch |
<: #ffcc50> [[GnomeBug:xxxxx|patch]] |
done |
<: #80ff80> [[GnomeBug:xxxxx|done]] |
not needed |
<: #80ff80> not needed |
Above are the states and corresponding markup to update the modules state table below.
Tarball |
Status |
core |
|
at-spi2-core |
not needed |
at-spi2-atk |
not needed |
dconf |
done |
evolution-data-server |
not needed |
glib-networking |
not needed |
gnome-bluetooth |
|
gnome-online-accounts |
not needed |
gnome-control-center |
not needed |
gnome-desktop |
not needed |
gnome-icon-theme |
not needed |
gnome-icon-theme-extras |
not needed |
gnome-icon-theme-symbolic |
not needed |
gnome-keyring |
not needed |
gnome-menus |
not needed |
gnome-packagekit |
done |
gnome-power-manager |
done |
gnome-screensaver |
obsolete |
gnome-session |
not needed |
gnome-settings-daemon |
not needed |
gnome-shell |
not needed |
gnome-themes-standard |
not needed |
gsettings-desktop-schemas |
not needed |
gvfs |
not needed |
mousetweaks |
not needed |
mutter |
not needed |
network-manager-applet |
not needed |
pulseaudio |
not needed |
telepathy-mission-control |
not needed |
core-utilities |
|
baobab |
done |
brasero |
|
empathy |
|
eog |
|
epiphany |
done |
evince |
done |
gnome-calculator |
done |
gnome-contacts |
done |
gnome-dictionary |
|
gnome-disk-utility |
|
gnome-font-viewer |
|
gnome-screenshot |
|
gnome-search-tool |
not needed |
gnome-system-log |
done |
gnome-system-monitor |
done |
gnome-terminal |
done |
gucharmap |
|
nautilus |
|
sushi |
not needed |
yelp |
|
core-extras |
|
gnome-backgrounds |
not needed |
gnome-user-share |
not needed |
vino |
not needed |
gnome-user-docs |
not needed |
core-fallback |
|
gconf-editor |
|
gnome-panel |
not needed |
metacity |
not needed |
notification-daemon |
not needed |
core-os-services |
|
accountservice |
not needed |
avahi |
not needed |
not needed |
|
dbus |
not needed |
gdm |
not needed |
not needed |
|
not needed |
|
polkit |
not needed |
upower |
not needed |
core-deps |
|
atk |
not needed |
atkmm |
not needed |
cairo |
not needed |
cairomm |
not needed |
cantarell-fonts |
not needed |
caribou |
not needed |
clutter |
not needed |
clutter-gtk |
not needed |
clutter-gst |
not needed |
cogl |
not needed |
dbus-glib |
not needed |
dbus-python |
not needed |
desktop-file-utils |
not needed |
enchant |
not needed |
expat |
not needed |
farsight2 |
not needed |
folks |
not needed |
fontconfig |
not needed |
gamin |
not needed |
gnome-js-common |
not needed |
gtksourceview |
not needed |
gdk-pixbuf |
not needed |
gjs |
not needed |
glib |
not needed |
glibmm |
not needed |
gmime |
not needed |
gnome-doc-utils |
not needed |
gnome-video-effects |
not needed |
gnutls |
not needed |
gobject-introspection |
not needed |
gst-plugins-base |
not needed |
gst-plugins-good |
not needed |
gst-plugins-farsight |
not needed |
gstreamer |
not needed |
gtk+ |
not needed |
gtk-doc |
not needed |
gtkmm |
not needed |
gudev |
not needed |
hicolor-icon-theme |
not needed |
icon-naming-utils |
not needed |
iso-codes |
not needed |
itstool |
not needed |
intltool |
not needed |
java-gnome |
not needed |
js185 |
not needed |
json-glib |
not needed |
libatasmart |
not needed |
libcanberra |
not needed |
libchamplain |
not needed |
libcroco |
not needed |
libdaemon |
not needed |
libdiscid |
not needed |
libgpg-error |
not needed |
libgcrypt |
not needed |
libgee |
not needed |
libgdata |
not needed |
libgnome-keyring |
not needed |
libgnomekbd |
not needed |
libgsf |
not needed |
libgtop |
not needed |
libgweather |
not needed |
libical |
not needed |
libmusicbrainz |
not needed |
libnice |
not needed |
libnotify |
not needed |
liboauth |
not needed |
libpeas |
not needed |
libproxy |
not needed |
librest |
not needed |
librsvg |
not needed |
libsigc++2 |
not needed |
libsndfile |
not needed |
libsoup |
not needed |
libtasn1 |
not needed |
libwnck |
not needed |
libxklavier |
not needed |
libxml2 |
not needed |
libxslt |
not needed |
mm-common |
not needed |
nspr |
not needed |
nss |
not needed |
p11-kit |
not needed |
pango |
not needed |
pangomm |
not needed |
pixman |
not needed |
polkit-gnome |
not needed |
poppler |
not needed |
py2cairo |
not needed |
pygobject |
not needed |
rarian |
not needed |
seed |
not needed |
shared-mime-info |
not needed |
sound-theme-freedesktop |
not needed |
speex |
not needed |
sqlite3 |
not needed |
startup-notification |
not needed |
telepathy-glib |
not needed |
telepathy-logger |
not needed |
telepathy-farsight |
not needed |
totem-pl-parser |
not needed |
tracker |
not needed |
vala |
not needed |
vte |
not needed |
webkit |
not needed |
yelp-tools |
not needed |
yelp-xsl |
not needed |
zenity |
not needed |
libnl |
not needed |
lcms2 |
not needed |
colord |
not needed |
apps |
|
accerciser |
done |
aislerot |
done |
anjuta |
|
banshee |
done (master and stable-2.6 branches, upcoming 2.9.0 and 2.6.2 respectively) |
bijiben |
done |
cheese |
done |
d-feet |
done |
devhelp |
|
evolution |
done |
file-roller |
done |
five-or-more |
done |
four-in-a-row |
done |
frogr |
|
gedit |
done |
ghex |
done |
glade |
done |
gnome-chess |
done |
gnome-clocks |
(done) |
gnome-color-manager |
done |
gnome-devel-docs |
not needed |
gnome-documents |
done |
gnome-klotski |
|
gnome-mahjongg |
done |
gnome-maps |
done |
gnome-mines |
done |
gnome-nettool |
done |
gnome-nibbles |
done |
gnome-photos |
done |
gnome-robots |
done |
gnome-sudoku |
done |
gnome-tetravex |
done |
gnome-tweak-tool |
|
gnome-weather |
done |
gtranslator |
done |
iagno |
done |
lightsoff |
done |
nautilus-sendto |
not needed |
nemiver |
|
orca |
not needed |
quadrapassel |
done |
rygel |
not needed |
seahorse |
|
swell-foop |
done |
tali |
done |
totem |
done |
vinagre |
|