Skip to content

Fastlane

You are strongly encouraged to use Fastlane in your app's repo – that way you have control over the contents of description etc, and they can be updated automatically with each new release. You can even use that to deploy your app to Google Play (should you really want it present there). And of course, F-Droid itself can also utilize it should your app be/get available there.

Your gains by using Fastlane

  • you can maintain summary/description in your app's repo and will not need to reach out to the repo maintainers at IzzyOnDroid or F-Droid each time you change them
  • you can provide screenshots which will be shown along with the description, raising the attention of those potentially interested in your app
  • you can even provide per-release changelogs, which will be shown inside the app's description, so folks don't have to „hunt them down“

While not mandatory, it's highly recommended for your apps' listing at IzzyOnDroid or F-Droid.org. Full Fastlane documentation can be found here. And if your project is hosted at Github, you can use this Github action to statically validate its Fastlane metadata (if you host it elsewhere: the author states it „just runs a Docker image with the compiled binary that one can run pretty much anywhere“).

Locations

For F-Droid.org, there are 3 possible entry-points the process looks for Fastlane, always located in the root of the app's repository:

  • /fastlane/metadata/android/<locale>/
  • /metadata/<locale>/
  • /src/<buildFlavor>/fastlane/metadata/android/<locale>/

For F-Droid.org's criteria, also see their documentation.

With IzzyOnDroid, the Fastlane „entry point“ (i.e. the directory directly preceding the /<locale>/ part) is configured per-app and thus not bound to a specific location. It must reside inside the app's source repository, though.

Structure

Items marked with ¹ are the minimum requirements (i.e. must be there), ² means „strongly recommended“. Consider ³ recommended, and all others optional:

/                                           (repo-root)
└── fastlane
    └── metadata
        └── android
            ├── en-US                       (en-US is required as it serves as fallback for missing locales)
            │   ├── short_description.txt   (short description, max 80 chars, plain text) ¹
            │   ├── full_description.txt    (full app description, max 4000 chars, basic HTML allowed) ¹
            │   ├── title.txt               (app name)
            │   ├── video.txt               (URL to a video introducing the app)
            │   ├── images
            │   │   ├── icon.png            (app icon; recommended especially for apps containing none) ²
            │   │   ├── featureGraphic.png  (promo banner, shown on top of the app desc in F-Droid client; landscape) ³
            │   │   ├── promoGraphic.png    (same, smallscreen size?)
            │   │   ├── tvBanner.png        (same, TV-screen size?)
            │   │   ├── phoneScreenshots    ²
            │   │   │   ├── 1.png
            │   │   │   ├── 2.png
            │   │   │   ...
            │   │   ├── sevenInchScreenshots/
            │   │   ├── tenInchScreenshots/
            │   │   ├── tvScreenshots/
            │   │   └── wearScreenshots/
            │   └── changelogs              ³
            │       ├── 100000.txt          (must correspond to versionCode, literally, no padding)
            │       ├── 100100.txt          (so this means: versionCode=100100, e.g. from app/build.gradle)
            │       └── 100101.txt          (max size: 500 bytes, plain ASCII (no HTML))
            └── ru
                ...
                └── changelogs
                    └── 100100.txt

Image sizes

  • icon.png: minimum 48x48, max 512x512 px
  • featureGraphic.png: either 512x250 or 1024x500 px
  • tvBanner.png: 1280x720 px (maybe 640x360 is acceptable as well?)
  • screenshots: large enough to show details giving an impression, but small enough to fit on small screens (and give not too much issues on bad connections/small data plans). If above mentioned Github action gives you an error like Error: 'max:min' edge radio should be at most 2.0: got=2.11 that means exactly what it says: height/width ratio should at max be 2:1 – so if your screenshots of the Eiffel Tower use the tower's original ratio, add more width to them :)

Formatting descriptions

This describes some specifics applying to the IzzyOnDroid repo, but also includes hints for your apps' listings at F-Droid.org and even Google's PlayStore:

Summary

This is the short_description.txt. It must not exceed 80 chars (which also applies to F-Droid, as it's defined by the fdroidserver software – which will simply truncate it at 80 chars); PlayStore limits this to 50 chars. It should describe the app as good as possible. For example, it should not simply be a copy of the app name, or a rephrase of it – but describe in short what the app does or what goal the user can reach with it. Keep in mind that this is often shown in lists, next to the app's name (so no need to repeat the name); if it sounds boring, most users will skip it 😉

Description

The full_description file. Again, do not just copy the app name or its summary – give some interesting insights! You have more room here (max 4,000 chars, though), so use multiple paragraphs, bullet-point lists etc. You can even use formatting:

TL;DR: For F-Droid repos, what works (and looks) best is HTML all put into a single line (to keep fdroidserver from messing it up while converting \n into <br>\n), as outlined below. If you also want to use the same description with Google Play, go with Markdown Lite.

HTML: basic HTML formatting (like paragraphs, links, lists, emphasis) are permitted – but there are also „forbidden html tags“ (for what is allowed, see e.g. HTML descriptions in the documentation at F-Droid.org). Avoid using headings (<h1>,<h2> etc) as you can never tell at which place in a web page your description might be included; at IzzyOnDroid those tags will simply be stripped replaced by paragraphs with bold (h4..h6) or bold-bigger (h1..h3) text. Make sure you use well-formatted HTML (e.g. do always include paragraphs inside <p>..</p> and have no „untagged text“, close tags you're opening), else results might look weird.

Google Play supports some basic HTML, too (see e.g. this comment at Github): a href, b|i|u, h1|h2, font color, br, HTML entities. Funnily, that info doesn't mention p or ul|ol – strange why those should not be permitted. However, their official help page also mentions pre as permitted, further stating lines should be broken at 80 chars. It references the Google HTML/CSS Style Guide which in turn explicitly lists ul|li and a lot more – unclear whether this would really apply to PlayStore descriptions (I doubt it as it even includes <!DOCTYPE html>). According to this article, it also permits small|sub|sup|blockquote|h3, while img|font size|center are reported not to work; a href is mentioned supported in 2016). As ever so often, the official page on this is nowhere to be found…

Summing up tags permitted on Play (with some confidence) from above research: a href, b|i|u, h1|h2|h3, font color, br, small|sub|sup|blockquote, HTML entities, Unicode.

Markdown: with the IzzyOnDroid repo, your full_description.txt (and only that) can also use Markdown (plain Markdown, not Github flavored). Again, make sure to head proper formatting (e.g. separate lists from surrounding paragraphs by a single empty line at front and tail, and separate paragraphs by a single empty line as well). As with HTML, headings will be stripped.

plain text: looks ugly. Make it at least close to Markdown, e.g. separate paragraphs by an empty line in between, so it can be parsed as such. Basic Markdown is not that hard to achieve! You can even use simple HTML formatting (like <b> or <i>) here, even <a href (though Play Store would remove the tags for these). This is a very good compromise if you want to use Fastlane with multiple targets as it works for F-Droid, IzzyOnDroid and Play Store – all 3 of them will sanitize, of course. This is what I call Markdown Lite.

If the F-Droid clients add to many blank lines when formatting the text: the only work-around to that I know of is using full HTML formatting (including <p>s etc) and keeping the entire text in a single line (Subway Tooter has a nice full_description.pl to maintain such a full_description.txt). This won't work if you need to include <pre>, but that cannot be helped at the moment; no way to make it perfect for everyone, sorry. At IzzyOnDroid, with Markdown and full HTML descriptions, the importer takes care for this „compression“ to a single line.

Screenshots

IzzyOnDroid only picks the phoneScreenshots for now. Please refrain from „framing“ your screenshots (especially if the frame does not provide any useful additional details but just waists space) – consider many users will browse your app information on their phones, using one of the F-Droid clients. Screenshots will always be „downsized“ to 350px on their small side and compressed – again with the users on their phones in mind: small data plans or bad connections should not have too much bad effect on them.

Updating your Fastlane structures

Descriptions as well as graphic files can be automatically pulled from Fastlane structures in an app's repo with each new release. For general Fastlane structures, please refer to the Structure section above.

Please let us know whenever you add „new elements“ to your Fastlane structure. If you e.g. had no screenshots there when your app was added, and now you have, we need to update Metadata here to reflect that or they won't be pulled.

Additional notes

  • screenshots can be PNGs or JPGs, no other formats are accepted.
  • F-Droid and IzzyOnDroid pick Fastlane from the very same tag/commit they build the app (or pick the APK) from. So make sure to have your changelogs/<versionCode>.txt there before you create the tag.
  • if you need different descriptions for different flavors: F-Droid supports a.o. /src/<buildFlavor>/fastlane/metadata/android/, so no need to revert to Triple-T (which is meanwhile in Maintenance Mode)
  • if you have fastlane structures on multiple matching locations, F-Droid.org will merge them (while IzzyOnDroid just supports a single location). This is especially helpful if you use fastlane supply to deploy to Google Play, which does not support ISO-639 language codes (like en or de) but insists on localized ones (en-US, en-UK, de-DE, de-AT etc): keep the ones to be used with fastlane supply in one location, and have the „simple ones“ in another.
  • for the official F-Droid client, which elements you have in your Fastlane structure does make a difference on if and where your app is shown on the „Latest“ tab, see: What are the criteria for an app to show up in the „Latest“ tab?
  • if you have questions on this, you can also consult Izzy's old Fastlane Cheat Sheet; Gist supports comments, where you might also find useful hints by other developers.