App developer feedback about quality guidelines

Hey app developers! I’m a volunteer working with Flathub, and I’d like to open up a discussion to better understand some things around the Flathub Quality Guidelines.

Non-developers: I love you, but I’m especially interested in hearing from the people making/maintaining apps, here. :slight_smile:

At the beginning of the year, we introduced new quality guidelines to enable curation of the best of what Flathub has to offer, including consistency around app names, icons, and screenshots. This enabled us to ship a brand new, beautiful design for Flathub including banners for featured apps. We’ve seen a lot of success from apps opting into and passing these guidelines—and as a result, we’ve had a nice set of featured apps rotating on the home page ever since.

However, folks have pointed out that it seems like it’s only ever GNOME apps that are featured. This is not an editorial decision of the Flathub team—this is simply a result of which apps are currently meeting the quality guidelines: over 90% are using GNOME technologies and at least generally following GNOME design guidelines.

That’s not in and of itself a bad thing (we love GNOME!), but it has lead to an inaccurate perception that Flathub is really only a GNOME thing—which of course is not true. While we’re supported in part by the GNOME Foundation, we’re a group of volunteers from the broader Linux desktop ecosystem space including both KDE and GNOME plus other/independent projects. We would really love to get more apps from other ecosystems featured on the home page!

So, we’d love to better understand and hear your thoughts:

  • Why are so few non-GNOME apps meeting the Flathub quality guidelines? Is it just that GNOME app developers more likely to meet the guidelines because GNOME Circle requires Flathub for distribution of apps, and has similar guidelines?

  • If you have an app on Flathub that doesn’t meet the guidelines, why is that? Are they too difficult to meet? Do you disagree with part of them? Do you not care about the benefits? Have you just not gotten around to it?

  • How can we improve the quality guidelines while still meeting the needs of Flathub: a level of consistency; the ability to craft beautiful, dynamic banners from the metadata; keeping Flathub looking/feeling modern to people coming from other platforms; etc.?

We look forward to your feedback; also, please share your app’s name/link if you’re willing so we have more context!

4 Likes

Some of the apps I package, don’t make sense in a banner IMO, so I never went through the motions.

1 Like

Here are my two cents as someone who published one application on Flathub that passes most guidelines and uses Gnome tech: http://ten-forward.sgued.fr/

Gnome optimizes very well for the case of “one developer wants to automate something or build a specific tool”, leading to a decent number of high-polish, limited functionality apps:

  • Libadwaita provides a very good set of default widget that look very good and integrate very well with Flatpak and the linux desktop: portals, dark/light theme, Wayland support, accessibility (to the extend it’s possible on current Linux)
  • Libadwaita is accessible from multiple languages, especially Rust, which has a community that want to be able to build GUI, and Python, which is a pretty decent language and easy to learn, and JavaScript for Dev coming from the web. QT on the other hand is native to C++ and thus has very poor bindings in Rust (based on what I hear. I’ve not tried them myself). I’m not aware of many KDE apps using Python, even though it appears to be possible. So you’re limited to C++ and JS, not languages I want to use.
  • Gnome provides some templates for logos, which allowed me to create on my own a logo that looks passable.
  • The screenshots are expected to be taken on Gnome, which include user shadows (looks like KDE also does that, but Sway which I use does not have that functionality, so I took my screenshots on Gnome), Cosmic (currently at least) doesn’t include a shadow either.

There are a ton of very small apps using gnome, because Gnome makes it very efficient to build such apps, but at the same time there are fewer “large” gnome apps, like Krita or Kdenlive (sure there’s GIMP, Firefox, LibreOffice that use GTK, but they seem much further from Gnome since not using its design patterns).

Overall my fell is that Gnome tech currently have the best DX for just getting started and building a simple app. I believe we can expect Libcosmic to also have a strong presence in the future for similar reasons, though maybe on a smaller scale due to missing functionality that will take a while to arrive and the lack of bindings for non-Rust languages.

This is coming from someone that does not enjoy Gnome as a DE, but likes a lot of the UI design of Libadwaita.

I published on Flathub because it makes it work across every distro, and doing that is what pushed me to “polish” my app with a logo, good descriptions and changelogs, since that was important in making it have a nice page.

I think the guidelines are mostly good! Maybe there should also be some efforts to clean-up the pages of older apps like Gimp and LibreOffice, which are still maintained but have old screenshots that don’t look good. The same applies to proprietary apps.

Maybe also the screenshots should be allowed to not be screenshots ? This might help more “corporate” apps. I’m thinking of allowing things that are more “designed” like the play store listing for Firefox:

Given that my app is for a niche use case. I could see myself trying to be more descriptive of what it’s for in my screenshots, but the guidelines ask for “Just the app window”.

The only guideline my app fails to pass is the non-technical summary, but I don’t really know how to solve that given that my app is pretty niche.

I am a developer that have published two apps in flathub.

I found difficult to comply with the logo guidelines unless I paid a designer who knows how to implement the flathub guidelines to make my logo instead of using inkscape by myself which I actually did in my last app but didn’t do in the first one.

I know it is very hard what I am asking, but when tasked with failing logo guidelines I could benefit if a more concrete description of what I am doing wrong and possible solutions to that were available.

There’s two reasons:

First i didn’t know/remember those guidelines existed.

Second, because the guidelines are too opinionated (and even worse I’m assuming there’s an human checking some of them, which makes for a terrible terrible system), let’s look at the 7 complains that there are on Okular:

3 are because of the icon:

  • Not too much or too little detail
  • No baked-in shadows
  • In line with contemporary styles

I don’t know who flathub thinks they are, but we’re not going to change our perfectly valid icon that we have used for decades because of whoever looked at our icon in what is effectively a third party site to Okular decided they don’t like it.

One is “No weird formatting or punctuation”, yeah whatever, more arbitrary definition of what is considered “weird”

One is “screenshots don’t use default settings”, what does that even mean? Yes, I have looked at the linked documentation and it is useless, no such thing as Default settings exist since every distribution on planet has a different default style.

One is “screenshots are not up to date”, what? Has the person even run the app? Because they look up to date to me

So out of the 7, 6 are questionable or plain wrong, the last one is “Has primary brand colors”, which Ok, we could add that, i personally find it is kind of silly to gatekeep on that, but whatever this one doesn’t bother me a lot.

1 Like

Thanks for the detailed reply, @sgued! I agree with your overarching point of the GNOME developer experience (including the icon templates, screenshot tool, etc.) making it easy to ship apps, which has lead to this sort of renaissance of GNOME apps.

Personally I really appreciate that Flathub requires screenshots to be just screenshots. I think if we wanted to support marketing images, that would be a separate spec—but I’d be more interested in making the presentation of screenshots more interesting. For example, pulling in the app’s brand color as the background behind them, and using the screenshot captions more prominently with more interesting typography.

The goal is to make it easier for an app developer to have a nice looking app listing, as automatically as possible. If we just have people freely upload whatever marketing graphics instead, it becomes a whole lot less consistent—and much harder for indie developers to stand out compared to those corporate apps that can hire an entire design team.

Ah, this is a tricky one! Yeah, I feel like it can be difficult to pass that guideline for apps that are inherently technical. In this case, I wonder if something simpler like, “Configure port forwarding” would work as the summary, then you can get more into NAT-PMP in the longer description?

But that’s good feedback to flag, anyway. Thank you!

2 Likes

The project that I have been getting heavily involved with has had a flatpak for a few years but it hasn’t been given a huge amount of attention, so one thing I’ve been taking on in the past few weeks is giving it some TLC.

I really like flatpak. I’d like it to take over from our AppImage as the main way we deliver cross-distro releases and the beta version.

As well as making sure the functionality matches the other versions, getting the flatpak verified and meeting the quality guidelines are key steps towards this, so I can tell you my thoughts on the guidelines so far.

(Though bear in mind that we haven’t asked for appraisal yet, so I don’t know how difficult the requirements are to achieve in practice, or how leniently our app would be reviewed – I’m going on the guidelines as written.)

  • I like a lot that they were created, I think they will help a lot towards making Flathub, and the general flatpak experience, both professional and user-friendly. In general they are very much a good thing, and most of the guidelines are sensible
  • Basically, however, I’m not sure achieving them as-written would be even possible for us. Complex programs in general – the likes of Photoshop, After Effects, Blender, GIMP, Inkscape, VS Code and IDEs – seem disadvantaged
  • Icons
    • Requiring high resolution icons and a reasonable size is good
    • Being picky about the style, contrast, and shadows are nice aims from a design perspective but means a lot of fairly good icons of well-known programs wouldn’t qualify. Ours, for example. I agree with @tsdgeos, that large, popular projects are not going to redesign their logo just for Flathub. It may be that the guidelines intended not for developers to change their usual logo but just to make an adapted version that works well for Flathub? But if that’s the case then maybe it should be explained as such, and maybe Flathub should allow submission of a different icon for Flathub than the usual one packaged with the app for use in the OS. Or is it expected that the flatpak app ships a different icon to apt?
  • Names
    • Most stuff is fine
    • The “weird formatting” restriction seems a little odd since that is something many tech companies and products rely on for branding. It says cases may be exempt if part of an established brand, but that is kind of just special treatment towards established projects and essentially says new projects aren’t allowed to do that, which doesn’t feel very “open” to newcomers
  • Summary
    • Most points are great
    • The length restriction is kind of arbitrary and ridiculously short. The summary is basically the equivalent of the GitHub “About” box, and looking at the repos I have starred, I don’t think a single one comes in at under 25 characters.
  • Screenshots
    • These rules seem really quite excessively restrictive, and honestly seem to be heavily biased towards simple apps – I have no idea how complex interfaces like the ones I named could really fulfil the brief
    • “Default settings” and “native decoration” are a slightly odd concept when flatpaks are literally designed to be run in many different desktop environments, no?
    • I tried and I literally cannot get our program small enough to fit within the tiny 1000x700 requirement without hiding UI elements. Some apps work well in such small window sizes (obviously we don’t want 1080p full-screen screenshots of file managers), but some are used maximized. How should Photoshop or something like that meet this criterion? Surely a better size requirement would be: “realistic for the practical use of the program, while maximizing visibility of UI elements”?
    • Requiring the titlebar and window decorations to be shown only makes the size limit worse. Plus, since these aspects are entirely DE-specific, what benefit do users gain from seeing them?
    • Requiring the full interface to be shown in all screenshots and a ban on cropping prevents us from highlighting aspects of the UI or showing the sorts of things that can be created and rendered in the program, as they get lost
    • I agree that marketing images are not what we want to see. But I think the requirement should be “captures of part or all of the interface during real usage”, not “full screenshots”
  • Release notes
    • Requiring them, and requiring them to be good, is excellent
    • The size restriction is pretty vague but seems to imply that most projects would have to significantly abridge their real release notes (as seen on GitHub, for example)?
4 Likes

I’m not involved with quality rating applications so I can’t answer everything but…

This seems like a mistake to me or an old rating? I don’t see the application name or summary having any weird formatting violating the guidelines.

I compared the screenshots to Calligra which passes the guidelines and was featured and to my naked eye I don’t see any difference that would cause it to be “not default platform style”. (Is it the red circle around the close button?)

Generally, I agree that a “platform default” is a bit vague and something that will vary between OSes. There should not be a reason to require it unless the screenshots are taken with a custom theme etc. that makes the app illegible or look broken.

You can still use the caption to describe things in the screenshot :+1:

Did you consider to reach out over one of the suggested channels. Checking it again, we don’t mention it as explicit as I thought. Only the blogpost directly links to the gnome and kde design channels to get help Raising the Bar: Introducing the new App Metadata Guidelines | Flathub Documentation

I can change the wording to Clear format if you feel that’s more helpful

The default of the DE is what we reference, not the distro.

This also references, if your window decorations are up to date in the screenshots. Oculars screenshots still use the old KDE style (at least it’s not the same as is used in screenshots on https://kde.org/ )

That’s mostly a technical detail, as we can’t generate a banner otherwise.

The shadow stuff is more of a technical reason, not really design. We can’t add shadow that’s consistent otherwise (same goes for desktop app stores). We could just add our shadows on top, but that would still mean, that some apps end up with stacked shadows, which would misrepresent those apps.

Contrast is important due to the dark design and to a degree the gnome dock always being on a dark background. Same for KDE and the light contrast.

I don’t think we care, as long as upstream is fine with it, it can ship whatever they want.

Context mostly. They can understand how an app works and we also get the rounded corner etc.

That’s not a restriction, mostly a suggestion, to make them useful to end users.

Probably due to it not being title case? View and annotate documents should be View and annotate Documents

Yes

The problem is if you are using a distro for a long time you aren’t going to know the default of the DE as you are tied to whatever the distro configured by default.

Someone using Ubuntu for the last 10 years is not going to know that GNOME upstream doesn’t have the minimise and maximise buttons on the headerbar as Ubuntu has been overriding them for 10-15 years.

Unless this reduces the overall screenshot quality, a “DE default” vs. “Distro default” should not matter.

And also seems impossible/impractical to enforce unless you are keeping up with the defaults of 20 different DEs across different release cycles and re-reviewing each specific element for every app again and again.

And, DIY window managers or compositors aren’t going to have their own “default settings”, the same way GNOME or KDE does. Most of them ship a barebones config file.

1 Like

The guidelines are specifically saying to use “sentence case”

The summary should not have any weird formatting or punctuation. It should use sentence case, rather than title case.

1 Like

Did you consider to reach out over one of the suggested channels. Checking it again, we don’t mention it as explicit as I thought. Only the blogpost directly links to the gnome and kde design channels to get help Raising the Bar: Introducing the new App Metadata Guidelines | Flathub Documentation

I read that, but I found unpolite to ask for free work when I plan to profit with my apps.

I have published multiple Gnome apps and I haven’t had difficulties adhering to the quality guidelines.

The only thing is in the Reasonable window size quality guideline it could be more explicit if the required size is for the screenshot or the window size, because with a window size of 1000x700px the screenshot taken in Gnome is 1122×822px with the shadow. Maybe even add the size that the screenshot will be taken in different DE with their respective shadow sizes.
This might make it easier to take screenshots of the correct size.

Sorry, meant to write that, as supported by the example :slight_smile:

We’re just checking, that it’s in the ballpark - nobody is counting pixels. It’s mostly a way to help authors, to have screenshots that are understandable on small devices/factors.

The 20-character limit on application names feels arbitrary to me, especially since it isn’t applied to translations. Probably because if they were, I bet no app would pass. Similar issue with Summary limits.

Some concepts just get spelled much longer in some languages! But if we think that’s a problem for English, we should care just as much about the UX for other languages.

I’d be more interested in removing/relaxing these limits and exploring better solutions for displaying longer names and summaries.

But at minimum, if we keep the limits, at least expose to app authors that some translations are too long.

I filed this issue about it, including some stats on names and their translations from a couple apps I maintain: Name & Summary length limits should probably consider translations too · Issue #3057 · flathub-infra/website · GitHub

2 Likes

I’m the developer of Community Remote. This is an open source GUI for the Roon music system. Roon is a niche in the music apps and the users that are looking for a Roon Linux GUI is an even smaller niche, meaning that I’m currently the only developer on this open source project. Community Remote is not a native GNOME or KDE application, it uses Flutter, so from the same code base also an Android and Windows version are built. For the Linux version the only supported distribution channel is Flathub.

When I published the first release on Flathub it was really the first alpha towards users so at that time the quality guidelines were not of importance to me (even didn’t know of their existence). At a later point I really made an effort to meet them, but failed on:

App Icon
Created an app icon myself (not being a graphics artist) and it did not meet the contemporary requirement. Haven’t tried to contact the suggested channels as the app is neither a GNOME nor KDE native app, and was wondering why anyone should stand-up for this.

Non Technical Summary
Updated this after the last review, so maybe it is okay now. I assume the Roon name is not considered technical, the intended audience knows about it, as the app is of no use without it.

Screenshots
Reduced their size after last review so are probably okay now. I was especially confused by the screenshots not being “up to date”, as the version stated in the app bar was the exact release at the time of review. Now reading through this thread I understand that the problem is probably the older KDE version in the window decorations.

My Feedback
That brings me to my feedback. Although I understand that, from the Flathub point of view, consistency is something to strive for, I think it is too restrictive at the moment. My app failed 4 checks at last review and will not be featured, effectively only because of its icon.

Could it not be a win-win situation if not only the apps with the maximum grade would pass? When I’m now visiting the homepage I have the impression that I’m always looking at the same small subset of apps. Maybe by lowering the bar a bit this subset would increase and more apps have the opportunity to get discovered by new users, something that is also of interest for Flathub.

Also, for users it might be helpful to have something to judge app quality apart from their appearance, e.g. by reviews, but that’s a different topic.

Sorry for having this long winded post as my first one on this forum, but the review kept me busy some time back, and now that you asked…

No it’s not. Unless there is a way for the reviewer to communicate what they consider “Not Clear format” it’s still useless, the deeloper gets a failed checkmark and there’s no way to act on it.

There is no such thing as default Desktop Environment either.

Again this is something that people should not have to guess when the checkmark is marked as failed, if there’s no way to know what the person decided is wrong, there’s no way to act on it.

Are you kidding?

Anyhow i guess most of my complaint is, I personally find the rules are kind of arbitrary, which makes them bad, but what makes it way way worse is that there’s no way to know why something failed so there’s no possibility of fixing even if one wanted to bow to the arbitrary rules.

3 Likes

It’s already in sentence case. Only first letter of the first word and the first letter of any proper nouns are supposed to be capitalised in sentence case. “documents” is not a proper noun.

But that’s beside the point. Things like this shouldn’t matter, there is practically no aesthetic or visual difference between the two that makes the other option a worse choice.

3 Likes

While I can’t guarantee it, I don’t think designers would care, that it’s not a gnome or kde app, if you reach out.

I think compliance with some of the criteria go from difficult to unreasonable for devs and packagers alike, and a lot of them seem to be influenced by GNOME’s app guidelines, which I think is why most featured apps end up being GNOME apps.

I do agree with most of the requirements, things like not having descriptions in the app’s title, or making sure the screenshots are just screenshots and not marketing graphics. But other criteria that has to do with an applications’ identity should not be up to the app store to judge.

For example with having the icon be ‘in line with contemporary styles’ is problematic especially with software that was made years ago but is still relevant. It’s not reasonable to expect the dev(s) of these apps to make a more modern icon just to publish on Flathub. A lot of older (or in some cases newer) apps are still popular with users despite having antiquated icons. In cases where these apps are not distributed by the original devs, the distributers don’t really have a choice in the first place.

When it comes to apps with ‘weird’ formatting in their names, it’s part of their brand. Things like ONLYOFFICE being spelled in all caps, or KDE’s NeoChat being spelled as one word, are perfectly fine and should be respected. Not having ‘weird’ formatting is very much part of the GNOME app guidelines.

There are a lot of popular apps people want that do not meet these standards, and being able to feature them imo would make Flathub more legitimate in people’s eyes - both with users and other devs. As in, 'Hey, all these big popular programs are here!". Again, I understand and support having such criteria to promote higher quality. One of my largest gripes with using Snap was that a lot of apps seemed hap hazardly thrown in there. I think Flathub did a pretty good job so far of having higher quality app metadata. But yeah, some of these criteria go too far.

7 Likes