Update screenshot guidance

[bertob]

The current appstream spec recommends this for screenshot sizes:

Ideally, all image screenshots as well as videos should have a 16:9 aspect ratio, and should have a width that is no smaller than 620 pixels.

This is not what we recommend to apps anymore, for a variety of reasons:

• Forcing apps into 16:9 often looks weird
• App store frontends have gotten better at dealing with screenshots with different sizes
• It's a pain for app developers to resize their app to this specific size
• It encourages large window sizes, which is the opposite of what you want here
• 620px width doesn't make sense for all apps, e.g. small utilities. Also, mobile screenshots are smaller than that by necessity.

I'd change this guidance to something more like this:

• Use an aspect ratio that works for the app's UI
• Generally try to keep the window size small to make the content more visible when it's scaled down in app store frontends
• Use window screenshots with baked-in shadows
• Use the default GNOME stylesheet, icon set, font, and window decorations

cc @pwithnall

[ximion]

Makes sense to me, except for the last point (AppStream is a Freedesktop specification, so we need wording like "use the default style of the desktop environment", rather than encoding GNOME)
I never really liked having these strict recommendations for screenshots in the specification anyway.

[vchernin]

Could it also be made more clear that different distros/packaging systems might have different screenshot resolution requirements? When I added screenshots to Tenacity I found it very confusing that different places had different resolution requirements, and I wasn’t sure of how it’s supposed to be handled.

Ideally the AppStream screenshots should be fairly high resolution in case someone zooms in to them right? It is possible to do so on Flathub.org or apps.gnome.org (on Firefox or Epiphany you can use touchpad zooming), not sure if GNOME Software is going to do that at some point.

This page should probably also be updated.

[ximion]

Could it also be made more clear that different distros/packaging systems might have different screenshot resolution requirements? [...]

No, because....

Ideally the AppStream screenshots should be fairly high resolution in case someone zooms in to them right?

...of this. AppStream has the concept of a "source" image for a screenshot (type="source" property on <image/> tags) which should be the highest reasonable resolution (please don't overdo it and create 50MiB images that zoom to infinity!).
If a distribution has different requirements, it is supposed to scale down the images and add them as thumbnails (type="thumbnail"), so the application author doesn't have to deal with it. appstream-util seems to be a bit strict there... (likely from a time when GNOME Software couldn't handle screenshots of different sizes very well).

[bertob]

An image of type source as well as any videos should have at least a width of 624 pixels.

Use an aspect ratio that works for the applications's UI, use 16:9 as long as that is sensible. Have the source screenshot be at least 624px in width.

The latest update still recommends a width of at least 624px, means no mobile screenshots are possible unless you're referring to 2x HiDPI here (in which case I think that should be clarified).

I'd maybe just say that this guidance is for desktop screenshots and apps with large interfaces only, but doesn't apply to small utilities or mobile screenshots of adaptive apps.

[ximion]

@bertob True! You can have a high-resolution mobile screenshot though, can't you? What is a reasonable minimal width for a phone screenshot? (If I take one on my Android phone, it's still a huge image even though the screen is small).

We could add a distinction between mobile and desktop apps on that recommendation, to make this clear, or even drop the specific pixel size requirement completely.
I also wonder if we maybe need a dedicated quickstart guide for mobile-only apps...
Btw, these are just recommendations, the AppStream documentation and specification follows RFC2119 in that regard. So you can already ignore recommendations and the resulting data will validate just fine and may at the most generate an informative hint.

[bertob]

If a portrait mobile screenshot is HiDPI it'd be 720px wide, but if not 360px. Personally I'd just drop this pixel size recommendation entirely, I'm not sure it adds anything.

[ximion]

I'm not sure it adds anything.

Me neither at this point :-)

[vchernin]

Do these docs need to be rebuilt or something? https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-screenshots appears to be on the older version (before 23d602b) still.

Also still outdated:

https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Application.html#tag-dapp-screenshots
https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html#qsr-app-screenshots-info

I do wonder why are there are 3 pages largely giving the same information? Is there a way this could be simplified?

I think the revelant source files are:
https://github.com/ximion/appstream/blob/master/docs/xml/metainfo-desktopapp.xml
https://github.com/ximion/appstream/blob/master/docs/xml/quickstart-desktopapps.xml (still says not 16:9 is bad)

[ximion]

No release has been made yet with these changes, so the online documentation is still for 0.14.5 - be patient ;-)

One of the pages you linked is a Quickstart guide, which exists just to help people to get started in a shorter form. The other is the actual specification which contains the definitive dos and don'ts for AppStream. Those are not equivalent, but of course there's some duplication, unless we want to redirect people from the Quickstart guide to the spec at every opportunity (which kind of defeats the point of the latter being easier to digest)

[sezanzeb]

baked-in shadows

What is this?