App developer feedback about quality guidelines

[KDE developer and involved with Flatpak on the KDE side]

I agree with many of the guidelines, but IMO a major problem is that some are effectively putting their finger on the scale, which helps to produce the observed effect of mostly GNOME apps ending up featured. For example:

  • The recommendation to avoid all uppercase and camel/pascal case in app names privileges apps from communities that already have these restrictions, e.g. GNOME. This is also not something the app author is going to be willing to change just for Flathub.

  • Almost the entire section on icon design essentially enshrines the GNOME icon guidelines as the thing to follow. Like your app’s name, you’re probably not going to change your app’s icon just for Flathub.

  • “Reasonable window size” privileges small single-function apps which GNOME has a lot of, and disadvantages large powerful apps that are designed to be used maximized.

  • “Do not use a mix of windowed and fullscreen screenshots” privileges apps without separate windowed and full screen modes that the user might want to see.

  • References to things like “your native system screenshot tool” and “Use the platform default configuration” are problematic due to the diversity of our ecosystem, as doing so may contradict another guideline. These feel a bit like they’re trying to avoid saying “Take your screenshot in GNOME or Plasma, using GNOME Screenshot or Spectacle.”

These examples aren’t actually objective quality guidelines but rather subjective style guidelines. And it’s notable what’s missing, too. For example the app naming guidelines don’t say “avoid the name being a single generic word like ‘Files’ or ‘Icons’ that would be hard to do a web search for”, which would disqualify almost all GNOME apps.

I think it would be worth going over the text to remove some of the opinionatedness that has the de facto effect of tilting the scale in favor of GNOME apps. Other opinionatedness that has to do with more objective quality is fine, but subjective style guidelines are always going to be problematic in a diverse ecosystem such as ours.

6 Likes

There are other recommendations that are not as clear as they could be IMO. For example:

  • “ideally phrase it in the imperative with a verb” starts with “ideally” which implies that it is not a requirement, but 100% of the “good examples” follow it. Is it actually a requirement or not? I hope not, because this would be quite awkward as applied to a lot of apps. For example Kate’s summary is “Advanced text editor” which IMO is okay. How would we rephrase that in the imperative? “Edit text in an advanced manner” ? :laughing:
  • “No weird formatting” is subjective and mildly inflammatory, and needs to be rewritten with a more neutral title and a hard-and-fast list of don’ts. Also it needs to be clarified that acronyms specifically are OK, since they’re all-caps and would otherwise fall under the “bad example” of an app with an all caps name. The reference to VLC implies this, but does not state it clearly.

Could be worth tightening these up IMO.

6 Likes

I’ll get specific about an app I co-maintain, Elisa. It’s currently failing three quality checks:

  1. Icon not good on dark theme - as mentioned earlier, not going to change the icon just for Flathub.
  2. Window too large - it’s a big app and a big screenshot showcases it well. The screenshot is perfectly fine IMO.
  3. Summary too long - “Play music and listen to online radio stations” (46 chars) is fine IMO, and even if I shorten it by removing “stations” (37 chars) it still wouldn’t fit. This is even a bit out of date as of a change I pushed upstream to change it to “Play local music and listen to online radio” (43 chars) to address the emerging impression many seem to have that music is a thing you stream from a big evil company, which is the one thing Elisa doesn’t do. Even if I shortened that as much as I possibly could to “Listen to local music and online radio” (38 chars) it still won’t fit. “Play local music and online radio” (33 chars) fits but barely but doesn’t feel as good to me IMO. I think 35 characters is just too restrictive.

There are also additional technical violations that the quality checkers didn’t catch:

  1. Technically, the second screenshot that lacks shadows because it’s full-screen and depicts the mobile UI. Technically this is a violation, even though obviously there’s nothing wrong with it since it’s advertising the fact that the app works on mobile with a mobile-optimized UI.
  2. Technically, the first screenshot doesn’t depict default settings since I took it while the titlebar had a non-default “keep on top” button added to it. Presumably the quality checkers didn’t notice, reflecting how minor and unimportant such a technical violation is.
  3. Technically, the UI is “out of date” in both screenshots because there have been extremely minor visual changes made to the app since the screenshots were taken.

There’s just too much rigidity here IMO. Even the checkers can’t keep up with the level of criticality with which they’re being asked to review apps’ presentation. It’s simply too much IMO.

5 Likes
The summary should not have any weird formatting or punctuation. It should use sentence case, rather than title case. It shouldn't end with a full stop.

Sentences should always end with a full stop or relevant punctuation.

1 Like

I tried to get many of the application I work on or at least remotely involved in KDE to fully passes all the checks. Until now, I only managed to pass all checks with Calligra.

One issue is that our release schedules is 4 months and I can’t backports strings changes to patch releases. So when I change any strings, I then have to wait ~4 months for any textual changes to see if I resolved the issue or not. For screenshots it is a bit better, because I can backport them but I still have to wait around a month to see if my changes are deployed and I unfortunately don’t have that big of an attention span.

I did update many screenshots ~8-10 months ago for dozens of KDE apps, specially for the introduction of this quality guidelines. But unfortunately they didn’t follow the ‘guidelines’, because I still used the old style of having a red close button instead of the new style of using a button with a transparent background and as such my screenshots were not using the default of the platform. This was super annoying and really significantly decreased my motivation to improve the metadata for Flathub. I am slowly updating the screenshots again but this is a large effort and I have a lot of other things to do.

I had other issues.

For Neochat, an issue I had, but which was recently recently fixed, is Do not display screenshots with environment="windows" · Issue #4105 · flathub-infra/website · GitHub . Since we use AppStream for more than just Linux but also Android and Windows, we added screenshots of NeoChat also on windows and properly marked them as for windows. Other than that I hope all the other issues will hopefully be resolved in the next release coming in 2 weeks.

For Tokodon, this looks good aside from a screenshot being to big. Again hopefully fixed with the next release in 2 weeks.

For KDE Itineray, most issues are easy to fix and the fixes should be available in the 24.12.0. release. But there are some unresolved issues. This applications uses a vertical layout and this seems to triggers “Reasonable window size” for the screenshots. The name is “KDE Itinerary” and this triggers “Just the name” :frowning: and the icon is also an issue because it has a very small shadow on the bottom but this is just the style used by most of our new apps Apps - Plasma Mobile I don’t think Flathub should be policing the icons unless the icon is very ugly.

Generally the window size requirement is also a painpoint for any a bit complex application. Trying to get small screenshots of Kdenlive or Krita is almost impossible and these are supposed to be lighthouse projects from KDE.

3 Likes

I maintain Flathub packages of two applications: Telegram Desktop and Kotatogram Desktop. Both packages got 8 (different) failed checks. Most of those (7) look like false negative to me for Telegram Desktop. And about half of them (4) for Kotatogram Desktop. I’ve mentioned all that in in details in issue: App Listing Quality has lots of false negatives · Issue #5900 · flathub/flathub · GitHub.

I very strongly feel that many of the screenshot guidelines should pretty much be the opposite of what they are currently:

  • Screenshots should be taken without shadows and without window decorations - if this is universally adhered to then padding and shadows and rounded corners can be added procedurally as desired
  • Screenshots should accurately represent runtime appearance of the current Flatpak version as closely as possible, for the largest or one of the largest groups of users, at the time that the current Flatpak version was shipped - distro, DE, settings etc. mustn’t be rigidly standard or bleeding edge, but the screenshots must not misrepresent the app in any way
  • If the app appears different in light/dark mode, the first two screenshots must demonstrate light and dark mode in that order
  • The screenshots should be sized such that they demonstrate realistic and actual usage of the app. All UI elements must be shown
  • The first (or the first two if light/dark) screenshot should additionally be as compact as possible while conforming to the above rules - I genuinely believe a sensible and representative size is something that can easily be judged on an app-by-app basis, obviously full-screen shots of GNOME Files are good to nobody, but also no one ever uses Blender in only a quarter of their screen
  • If the app is typically used in full-screen mode or in mobile format, these should be demonstrated in at least one screenshot
2 Likes

I am currently, trying to make Install Kontrast on Linux | Flathub passes the checks. And while most are trivial, one is hard: the icon.

KDE HIG requires colorful to have 4px margins, it seems flathub requires 2px margins, which means the apps doesn’t pass the following check “Doesn’t fill too much or too little of the canvas”

See Colorful Icons | Developer

there are DEs that can not do screenshots like that

1 Like

personally i discovered today that there are checks, i’m thinking i’m already inside the guldelines.

i will fix it as soon as possible

Maybe I’m missing something, but surely a screenshot that includes the extra stuff can just be cropped appropriately?

If you want to figure that out, be my guest. I’ve invested multiple days at this point. There is some history here Detect screenshot transparency · Issue #544 · ximion/appstream · GitHub but the other github user that I was talking to in that issue is gone.

Please make sure, that screenshots also include rounded corners according to DE specs and anti aliasing still works. We also can’t loose stuff in the middle of the picture or downgrade image quality significantly.

If anyone is trying to make their apps pass and has specific questions or problems like the ones above (and not general feedback for the entire guidelines), I suggest opening an issue using the quality guidelines template.

This is also now linked in the quality check sidebar on flathub.org, so you can open an issue directly from there as well and ask for clarifications.

1 Like

Late to the party here, developer of NX Dump Client. Currently failing checks, some well deservedly (will fix once I get to it, I promise…), some (IMO) not so much. General feedback:

  • 35 characters is a bit restrictive for a summary, especially if you have to mention name of some existing brand/tool, something like 50 or maybe even 60 seems like a more sensible limit.
  • A little mixed on “[App description] understandable for a non-technical person” - I think mine is perfectly understandable for its target audience, which is admittedly a little the on technical side, and I can’t really make it both more understandable for a non-technical user, include mention of nxdumptool (which is crucial to what the program does), and stay withing the 35 character limit: “Dump Switch games over USB” is probably more understandable but lacks the vital detail, “Dump Nintendo Switch games over USB with nxdumptool” seems like the perfect medium to me but is 51 characters long (42 without Nintendo). Maybe the length restriction is the primary issue here, after all.
  • Mostly valid criticism of the app icon (I plan of scaling it down to appropriate footprint with rounded corners and a colored outline), but I like many others here have ideological issues with “In line with contemporary styles” - I’m admittedly not much of an artist, but as long as the icon doesn’t cause practical issues (something the rest of icon guidelines strive to cover already), IMO it should not be judged by the distribution platform; I’d understand it if the app officially became a part of GNOME project, but Flathub evaluating the icon against third-party guidelines seems wrong to me. More specifically, mine is purposefully styled after the icon of nxdumptool itself, and does not try to follow designs of either GNOME of KDE projects.

“Just the name” failing is something I probably should just contact reviewers about directly, since “NX Dump Client” is really what my program is called, “Client” being a part of the name (evident from the icon) and “NX Dump” not actually existing. Say what you want about my naming talents, though.

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?

I’m a bit late to the party in this discussion, although I’ve been maintaining some packages since 2019.

Most of the packages I maintain are cross-platform video games and those developers don’t focus on Linux primarily, thus making it almost impossible to meet Flathub’s standards, especially since Arch and Debian seem to be cool with those identical packages. in fact, the biggest problem I’ve ran into with having some applications maintained, is that over the years those strict guidelines add up to an increasing amount of paperwork that many projects will not commit to.

Meeting guidelines

I would like to have all my packages meet guidelines, but to answer your guestions in a strait-forward fashion.

  • Are they too difficult to meet? Yes
    When I go to FLOSS developers that maintain old videogames, they are fine with Flathub in the same way that they are fine with Arch or Fedora. All good as long as they don’t have to focus on it. For them, it’s too much work since Linux users are only 10% of their customer base.

  • Do you disagree with part of them? Yes
    When existing packages have been online for years, they should be grandfathered into old rule-sets. Flathub is only causing more friction, possibly stalling security updates and giving Flathub users a sub-par experience.

  • Do you not care about the benefits? Yes
    What benefits? Being featured in the Software Center carousel? People that want to use DBeaver or GZDoom already know what it is. And since most FLOSS developers don’t actually focus on Linux, the gains for them are insignificant.

  • Have you just not gotten around to it? Yes
    If time was infinite, I could help all these upstream projects to meet all documentation and format guidelines from Flathub. But that’s not the case so I focus on the biggest gains, leaving the documentation-breadcrumbs for later. I very much strife for a 80%/20% balance in my life and I’m not wasting my free hours in getting that last 20% done.

Striving for perfection

This leads to another, underlining problem that has been causing some friction with the Flathub project; Perfect is the enemy of good. Regular users are encouraged by developers to use the unsandboxed deb-version of a certain game engine because the Flathub version is rejected or not updated due to some shifting policy. I have no expectation that any of the packages I maintain will ever meet all guidelines, even when some have 500.000 downloads.

It’s not hard to find many more applications with pending security updates, stuck on a linter-validation. This one happened to me today:

And there are package submissions stuck in limbo due to changing policies here on Flathub, essentially just telling customers to use the .deb version instead. I have had the great displeasure of trying update existing applications with changing application Ids, only for the entire project to come to a hold because of these changing guidelines:

Closing comments

Keep in mind that Flathub is not just competing against Snap, it’s also competing against .deb files and the AUR. Their guidelines are very lax for a reason. Flatpak is the way forward, but all the extra hurdles that Flathub presents are not encouraging. No wonder that professional businesses prefer Snap.

As for why all the GNOME packages get featured… When GNOME makes the rules, and those rules have very little consideration for cross-platform packages, existing expectations or continuity… then you’ll find that only GNOME packages adhere to the rules. And yes, this is a recurring problem with the GNOME project, but let’s focus here on Flathub and not on their project as a whole.

sorry but i don’t understand your objections, i manage apps where i managed to fit the guidelines and others where it is not possible, and all of them are on the store.

the guidelines are optional and are mainly used only to have a graphically coherent flathub homepage. no one will remove your apps if they do not fit the guidelines

1 Like

In my previous writing, I was perhaps a bit vague, complaining about Flathub missing the forest for the trees. Let’s not digress, and allow me to give you a simple example.

The only reasonable arguments I would have against it being a ‘featured’ application are:

  • Application is not suitable for all ages
  • Application relies on third-party extra-data

Two criteria who are currently not even part of the official ‘featured’ review process. Instead, we have the following arguments:

  • Name uses weird formatting
  • Logo is old-fashioned
  • Summary to long
  • Description to technical

It’s absurd. Who is the Flathub project to decide that what icon they can have, or what they think is important to write in a description?

Proposed quality guidelines

General

  • No trademark violations
  • No third-party (i.e. extra-data) wrapper

Support

  • Same-day updates as non-flathub packages
  • Customer support for Flathub package
  • 95% feature parity compared to non-flathub packages

Metadata

  • Brand colours
  • Release notes
  • Links (url info for bug tracker, repo etc)
  • All the things part of the regular review process

Icon

  • Scalable version
  • 128px version

Name and Summary

  • Basic description of the project
  • No profanity, no Code of Conduct conflicting content

Screenshots

  • Multiple screenshots
  • Actual content
  • Up to date content
  • From a common Linux desktop distribution (i.e. Ubuntu, Linux Mint Cinnamon, RHEL 9, Manjaro KDE)

Additional

  • All ages
  • International (i.e. no local government app)

i repeat again:

the guidelines are not mandatory to be on flathub. they are advice that you can or can not follow.

if you can and if you want follow it, otherwise don’t do it

1 Like

At risk of ending in a circular discussion with somebody on the internet…

I’ve given you multiple examples on how the additional Quality Guidelines are at best useless, and at worst obstructive to day-to-day operations as a package maintainer.

Over the past five years contributing to Flathub has become harder, which is something you see since companies like Microsoft and Jetbeans have chosen Snap. And yes, these additional roadblocks are a part of that.

This assumption is wrong, the logo is fine from flathub POV. Real problem is, it’s too big.