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:

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:

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:

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:

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:

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:

• Endless Sky
• GIMP
• Blender

Get out there and make some apps look good!