How to make an app look good in Discover

Why do some app pages in Discover look good, while others look half-finished at best? Why is it that sometimes in some distros (Like Ubuntu 16.04 and KDE Neon) almost all of the app listings are bad? We’ll dive into that today, and see what the plan is for fixing it.

First thing’s first: Discover does not control an app’s presentation. Instead, we display app metadata (such as screenshots, the description, and links to the app’s website) made available to us by the software’s packagers. It’s all up to them to pass on the metadata. If they don’t give it to us, we can’t display it to you!

Where does this app metadata come from? The app developers themselves, from their AppStream file. If an app doesn’t provide an AppStream file, or its file is very minimal and doesn’t provide much content, then the packagers have to create this information themselves. Some packagers do a better job of this than others, as we’ll see. Ubuntu 16.04 is a particular offender, and while it’s gotten better in later releases, every distro based on Ubuntu 16.04 (like KDE Neon) will unfortunately inherit its deficiencies of metadata-poor packaging. This causes app listings to look bad, and frustrated users blame us or the software developers–almost never the distro, even though they make this their job!

Here’s an example of what good AppStream metadata can do for an app:

Perfect Hexchat.png

It’s got:

  • An attractive, high-resolution icon
  • A screenshot
  • A short and useful description
  • A human-readable version number
  • A license
  • URLs for the homepage and user guide, plus links to pages where you can donate or report a bug.

All apps should look this good! It’s pretty easy to get there if developers put lots of information in their AppStream metadata files, and if distros and other software sources make it available to us. Here’s Hexchat’s AppStream file. This is what a good AppStream file should look like! (there’s only a single problem: the ID is set using a non-recommended form: io.github.Hexchat.desktop. This string shouldn’t have “.desktop” on the end of it).

So what’s the plan? We need to get app developers to improve their AppStream metadata. This is an ongoing effort that I’m heavily involved in, but like everything in the FOSS world, it will go much faster if you help!

How users can help

Let’s say you stumble across an app listing that looks like this:

Bad Filezilla.png

There’s no screenshot, and the text looks like it was formatted using Markdown, which isn’t formally supported in most software center programs like Discover, so it shows up as an ugly wall of text. The license is “unknown”, and there’s not even a URL for the app’s website! What a mess.

Here’s another:

Bad HoDict.png

This app provides a low-resolution icon that isn’t very attractive. Its caption (“Ho22bus’s Dict”) gives no indication what the app is or does. As before, the description appears to use markdown rather than HTML, and provides no license or relevant URLs. The app is a mystifying black box.

Here’s how you can help software developers!

First, find the app’s source code repository. Then, within that, locate the AppStream file. It’ll be named something like[appname].appdata.xml. If it looks fine in the developer’s source repo, and you’re using a distro that ships old software like Ubuntu or Debian, it’s likely that the distro packagers simply haven’t included an up-to-date version of the AppStream file, so file bug on the distro’s packaging itself asking them to.

If the file is subpar… then fix it! On the technical side, check out Hexchat’s AppStream file for a great example of how it should look. Design-wise, here’s a great guide from the ElementaryOS people on how to write a compelling app listing that’s largely applicable to Discover as well.

In some unfortunate cases (e..g. Blender), there may not even be an AppStream file. Well, submit one for them! This stuff is really important!

Make sure to validate the file using an XML Validator, and then once it checks out as being valid XML, run appstreamcli validate on it (you may have to use your distro’s command-line package manager to get appstreamcli). Once it passes both checks, submit it back to the developers, either in a bug report, or even a patch or pull request if you know how to do those things.

How developers can help

Please: provide downstream packagers with AppStream files that you’ve taken the time to craft with love and attention to detail. Distros may do your packaging for you, but they’ll never care about presenting your app nicely as much as you will!

If you don’t supply packagers with high-quality AppStream metadata, you’re making life harder for packagers, and your potential users may well be presented with an ugly, even repellant app listing in software center apps like GNOME Software and KDE Discover. Users may blame you, or they may blame us, but either way, they’ll be looking for someone to blame, because bad or nonexistent AppStream metadata will make your app look bad, guaranteed. Here’s the spec. Follow it, and make your app look beautiful, and users will trip over themselves to install and use your software.

Also, submit your app to Flathub! The Flathub people are easy to work with and are delighted when you include high-quality AppStream metadata. Which leads me to…

Flathub rocks

I want to give a shout-out to the people who run Flathub, the de facto central repository of Flatpaked software. They take their role as packagers seriously, even going so far as to create high-quality metadata for apps that lack it. For example, here’s the version of Blender packaged in KDE Neon, which comes from Ubuntu 16.04:

Blender bad.png

Doesn’t look too great, right? Blender is amazing, but you wouldn’t know it by looking at this. Sadly, the Blender developers don’t provide an AppStream file, and the Ubuntu packagers didn’t do anything about it. So Blender’s app page looks lousy.

But here’s the Flathub version:

Blender good.png

Isn’t that way better!? Lots of screenshots, paragraph breaks, a license and website URL… all that information was added by the Flathub packagers. Now that’s dedication.

Want to help out? Be like the Flathub people and improve the metadata for your favorite apps, but then go even farther: submit your changes back to the developers! Here are some examples of minimal patches I or others have submitted to give you a sense of how easy this can be:

Get out there and make some apps look good!

8 thoughts on “How to make an app look good in Discover

  1. Another good post.

    “the description appears to use markdown rather than HTML”

    I think you ment to say XML here as the only HTML currently supported by AppStream metadata is said to be paragraphs and ordered/unordered lists.


  2. I’m making some contributions, but I noticed that many apps (such as Inkscape and darktable) are using underscores in front of some of the tags (such as , ). This makes validation fail and it’s not in the specs.

    These underscores seems to stem from a recommendation given some years ago for projects using intltool for translations:

    Is this recommendation still valid? How do we handle apps that uses underscores like this?


    1. Thanks so much for your efforts here! That’s a great question, and likely one better suited for Richard Hughes or Matthias Klumpp (the AppStreasm maintainer: I would probably omit them if you’re writing new content, but respect them for existing content.


    2. Thanks for *your* efforts! 😉

      The reason to projects using invalid underscore prefixes was indeed caused by some limitation of the now depricated intltool. The prefixes are for intltool to allow to translate the tags. The better solution to this mess would be to either validate the translated files instead of the source files or ignore the errors for now. Either way we should ask projects to migrate to gettext.

      Citing a email from Matthias on this:
      “If you can, switch the project to modern Gettext and away from the old Intltool (it’s deprecated and not needed anymore). If you can’t do that or don’t want to do that or the project doesn’t want to do that just yet, you can also validate the translated file instead of the source file.”


Leave a comment

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s