Fastlane file structure ($1895688) · Snippets

What is the content and format of the Changelog file names?

Does there need to be an en-US entry as the default, or can we use any languages we like?

Thanks! Updated the snipped to make that clearer. More verbous:

Changelog file names must correspond to the releases versionCode, literally (no padding; so if the versionCode is 1, the file name should be 1.txt
in my experience, en-US is needed by F-Droid as it's always used as fall-back (so if someone comes with a locale not available in Fastlane, en-US seems what is looked for). You can add more locales, of course.

Does it support flavors with different app ids?

/                                           (repo-root)
└── fastlane
    └── metadata
        └── my.app.id_1
            ├── en-US                       (en-US seems to be required by F-Droid)
            [...]
        └── my.app.id_2
            ├── en-US                       (en-US seems to be required by F-Droid)
            [...]

No. To my knowledge, that's only supported by Triple-T. Where you now put the "my.app.id", Fastlane expectes the target OS (as far as I understood the docs).

Hello @IzzySoft and others, Do you think its acceptable for outside contributor to create the fastlane structure for apps and ask for merge or its better for the main developer to handle that ? Of course it depends on personal developer preferences if he/she accepts, but I am asking for any technical reasons against.

@DuMuT6p it's of course fine and much appreciated – that's how F/LOSS is supposed to work! That merge/pull request must of course be opened against the corresponding app's repo, as that's where Fastlane is looked for. And it's of course up to the corresponding repo owner/team to accept.

As setting up Faslane doesn't require any programming skills, I'd even recommend that as a way a non-developer can contribute. And I see no (technical) reason why any project should reject such an offer, provided the content is fine 😉

@IzzySoft What are the recommended sizes/ratios for featureGraphic, promoGraphic, and tvBanner?

Or is any landscape resolution good?

I haven't found that mentioned with Fastlane. But they should correspond with those specified with the Triple-T file structure:

featureGraphic: 1024x500 (I've often seen half that size, i.e. 512x250, so that should be OK as well)
promoGraphic: 180x120 (no idea where it's used, to my experience it is very safe to skip)
tvBanner: 1280x720 (as with promoGraphic, no idea where this is used)

Thank you!

And another question, how frequently are those data picked up?

If I make a change, within how many hours will it be available in the store?

That depends on the store. Assuming you refer to F-Droid: it's picked up whenever a new release is build (i.e. usually within a few days after your creating the corresponding tag). Note with F-Droid, Fastlane is bound to the tag the APK was built from – as is the code, of course, so they correspond to each other.

Got it, thank you

Ok, and the last question, what is the format of the locales? en-US and ru as in the example

UPD: got it (https://www.andiamo.co.uk/resources/iso-language-codes/)

I guess the changelog must be included into the tag for fdroid to pick it up or?

Yes. F-Droid picks up Fastlane from the very same tag/commit the app is built from. Other than that, the updater for my repo looks at HEAD.

@tom79 Please check my updated snippet: I was wrong! You can use multiple fastlane locations, including flavor-specific ones. No need to revert to Triple-T for your tubes and nitters 😃

@IzzySoft Ah! Thanks. I will revert to Fastlane. I have issue with Triple-T

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

@IzzySoft It seems last update of UntrackMe and Tubelab failed with fastlane and flavors :(

Does flavor name need to be in camelcase in /src/?

@tom79 mind opening an issue for that (not sure whether fdroiddata or fdroidserver are a better fit), so we don't clutter this snippet? Please include the repo link then so we can check. That part (what was planned and what's already implemented) is outside my horizon currently. I'm drowning in RFP and MRs, trying to decrease the huge backlog… In short I'd expect it must use the same "case" as the flavor itself uses (i.e. exact match on case-sensitive compare).

@IzzySoft My bad, I was using /<module>/src/<buildFlavor>/fastlane/metadata/android/ (not yet implemented) instead of /src/<buildFlavor>/fastlane/metadata/android/

but I am asking for any technical reasons against.

yeah, i was wondering the same. the special context being - that i guess there is some form of auto-changelog available. And have doubt that maybe the project is using that - which i/outsider may be unaware of. So, that can be an error.

But i am not even sure if auto-changelog even exists for real or just in my mind ;)

But i am not even sure if auto-changelog even exists for real or just in my mind

There are workflows for that, yes – Github actions and other things, even "platform independent" projects scraping it e.g. from the commit history. But that goes beyond this snippet, so please let's not discuss it here and rather stay focused 😉

@IzzySoft I have a few questions regarding what is allowed:

~~Are pictures (for example the phoneScreenshots) allowed to be .jpeg or must they be .png?~~ EDIT: According to https://f-droid.org/en/docs/All_About_Descriptions_Graphics_and_Screenshots/#image-file-formats, .jpeg and .jpg should be fine as well!
Is it fine to put other files (for example the gimp-files) into this file structure, or would that interfere with builds? (see here for an example)
Is the -tag supported? (something that is similar to the -tag.)
In full_description.txt, are tables allowed? What about CSS-styles? This is what I am currently writing:

Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text. Some Text.
<table>
  <tr>
    <th style="white-space: nowrap">Week 1:</th>
    <td>Just step outside on the street, then return home.</td>
  </tr>
  <tr>
    <th style="white-space: nowrap">Week 2:</th>
    <td>Take a walk around your house/building.</td>
  </tr>
  <tr>
    <th style="white-space: nowrap">Week 3:</th>
    <td>Take a walk spanning 3-5 buildings.</td>
  </tr>
  <tr>
    <th style="white-space: nowrap">Week 4:</th>
    <td>Take a longer walk and add short jogging-segments into the mix.</td>
  </tr>
  <tr>
    <th style="white-space: nowrap">Week 5:</th>
    <td>Go jogging. Well done.</td>
  </tr>
</table>

@Glitchy-Tozier some of that is answered behind the initial links.

screenshots can be either .png or .jpg
other files should not be placed here – only what's described. We had cases where additional files caused issues. Should not – but definitely does not if it's not there, right?
for F-Droid, see forbidden html tags. Other stores might handle it differently (e.g. Play AFAIK strips all tags). The style attribute mostly works with F-Droid.

Thank you for your reply!

screenshots can be either .png or .jpg

This may be a stupid question, but does that mean .jpeg, will also work?

for F-Droid, see forbidden html tags. Other stores might handle it differently (e.g. Play AFAIK strips all tags). The style attribute mostly works with F-Droid.

Great, I'll be really interested in how F-Droid handles my table, then!

@IzzySoft Do you know of any size restrictions regarding the icon.png?

This may be a stupid question, but does that mean .jpeg, will also work?

And as we found out: at least for F-Droid the answer is "yes".

Do you know of any size restrictions regarding the icon.png?

@Glitchy-Tozier not by definition, only by observation: it should be at least 48x48px, and at max 512x512 – steps in between seem to match what is usually taken in the midmap folders inside res/ – so 96x96 would be another valid size. IIRC I mostly saw 192x192 here, but I might remember that wrongly; smaller sizes I rarely observed.

@IzzySoft Thank you, I'll try my luck with 512×512 then!

One last question (maybe 😉):

Do you know how files are prioritized across localizations? Say we have a normal app-icon, we have a fastlane/.../en-US/pictures.icon and we have created fastlane/.../de-DE/ but don't have an app-icon inside our German fastlane-folder.

Where will F-Droid now grab the icon from when displaying the German metadata? Will it use the actual app-icon or will it grab the one in fastlane/.../en-US/pictures.icon?

Apart from the fact that en-US/pictures.icon is a totally wrong location & name (so this file would be ignored at best, or even throw errors), what doesn't exist in one language (including screenshots, descriptions, everything) is always looked for in en-US, which is used as fallback and hence mandatory. And your icon would need to be en-US/images/icon.png 😉

Ew, yeah, i mistyped! No idea how i turned images/icon.png into pictures.icon 🤣

Anyway, that's great to hear! I was afraid I'd need to spam my metadata with redundant pictures, so it's nice to know that one of them will suffice. :)

Ty again!

Hello, Thanks for those explanation. I have a question. My application is for french speakers only. As I understood I need en-US/images/icon.png, en-US/title.txt, but is en-US/full_description.txt", and all the files in en-US` mandatory?

Thanks in advance

Hi @jfoucry,

as en-US is used as fallback for all missing details (if I e.g. use a de-DE locale which does not exist in your Fastlane structure), it is required. But it does not necessarily need to be "fully equipped". The bare minimum is short_description.txt and full_description.txt. I'd also recommend placing the graphics (icon, featureGraphic, screenshots) into en-US instead of into fr (or fr-FR), so they are available to all locales.

Further, no need to be too detailed with the full description in en-US – but include as much that it's roughly clear what it is about, and that the app targets French speakers only.

By the way, title.txt as well as video.txt are purely optional for all languages. If there is no title.txt, the app's name should be used – and if there's no video.txt there's no video (so also no need to place an empty file for those).

In full_description.txt, would it be possible to disable newline-to-  conversion adjacent to HTML block-level/listing elements (, <ul>, <li>)?

For example in my entry, break elements get inserted between paragraphs, lists, and list items:

The extra spacing looks ugly. More importantly,   as a child of <ul> doesn't validate:

Error: Element br not allowed as child of element ul in this context. (Suppressing further errors from this subtree.)

[...]

I would prefer not having to collapse the HTML onto a single line (which is not great for git diffs).

@yawnoc newline-to-br conversion got nothing to do with Fastlane structure. That's something you'd need to report to F-Droid (fdroidserver repo, as that's where the conversion takes place when Fastlane is imported). If you take a look at apps in my repo, you will see there is no such thing as this conversion (unless explicitly set), as import is handled differently (skipping the fdroidserver conversion step).

You can partly work around that by using what I call "Markdown light", as described in my wiki (also mentioned in above snippet: second-to-last bullet point). That's not ideal, but looks a little "less messy".

Thanks @IzzySoft!

I have done some spelunking in fdroidserver and realised that the conversion is done separately in fdroid-website and fdroidclient.

The issue has been reported (but not fixed), and it is a non-trivial one because the collection of all existing description files is a hodgepodge of HTML, MediaWiki, and plain text.

I've just bumped fdroid-website#247 with my observations above. The equivalent client issue is fdroidclient#1776. In the meantime I agree that plain text is the best way to go.

I agree that this would be a necessary fix. Personally, I eventually gave up and used the actual "•"-character to act as if it actually was a list.

<strong>Example of a Habit-Plan:</strong>
Final Habit: <i>Go jogging every morning</i>
Levels: <i>Every morning...</i>
<b>• Week 1:</b> Just step outside on the street, then return home.
<b>• Week 2:</b> Take a walk around your house/building.
<b>• Week 3:</b> Take a walk spanning 3-5 buildings.
<b>• Week 4:</b> Take a longer walk and add short jogging-segments into the mix.
<b>• Week 5:</b> Go jogging. Well done.

Bad idea, @Glitchy-Tozier. Had you used the standard asterisk (without surrounding it in HTML tags), it could be parsed as Markdown (which e.g. my repo does) and format fine:

<strong>Example of a Habit-Plan:</strong>

Final Habit: <i>Go jogging every morning</i>

Levels: <i>Every morning...</i>

* <b>Week 1:</b> Just step outside on the street, then return home.
* <b>Week 2:</b> Take a walk around your house/building.

See here for formatting hints. Note the empty lines:

surrounding the bullet-point list: there must be an empty line before (or Markdown would merge it into the previous paragraph)
after each of the introducing lines: to make them separate paragraphs (could be skipped if you're fine with it being a single paragraph when parsed as Markdown; lines would still be separated then at F-Droid)

@IzzySoft Does regular Fdroid use Markdown though? I'm using the regular repository.

@Glitchy-Tozier currently not. That's why I linked to my wiki where the details are explained (what I call "Markdown light" works well for both – and you'd be prepared should F-Droid one day support Markdown there). Please understand that a Gist is not well suited for discussion, so I try to keep that part short here 😉

@IzzySoft This was helpful! Thank you so much.

Thank helpful too 👍

Sorry about this, but I'm somehow subscribed to this and have no idea why. Any ideas of how to unsubscribe? I can't find the right-hand list where the option should be.

Sorry, but no idea. The GitLab docs don't say. Maybe check with GitLab support. If you find out, I'd be curious to know, too!

#note_1369921740

@IzzySoft, thanks. I've posted forum.gitlab.com/t/89184/1.

Is it possible to set an arbitrary repo ? We set up something separate to avoid polluting commit history of our main app repo ? https://github.com/openfoodfacts/fastlane-descriptions-smoothie/ https://github.com/openfoodfacts/smooth-app

@pierre82 make a separate repository. Inside that, start the Fastlane structures at "level 2" (i.e. skip /fastlane and start right with /metadata). Then add this repo as a git sub-module to your app's repo in its root, giving it the name fastlane. That way, when the sub-module is checked out with the app (submodules: yes in the build block of F-Droid's YAML), it will work the same as if it was part of the app repo itself.

This will reduce the "pollution" – but will still require at least one commit when updating for the next release. With your app in my repo, you'd not need to integrate the sub-module but would need to let me know where the Fastlane structures are – as I use a different mechanism than F-Droid.org, I can specify any valid alternative location (where "valid" means a valid Fastlane-structure either in a Forgejo/Gitea, GitLab or Github repo) – but with F-Droid.org you will.

Though I wonder if those "fastlane commits" would really add so much overhead. How often would they happen? On average, I guess not much more than 1-2 times per version/release. So I'm not sure if that's worth the trouble 😉

-- So I'm not sure if that's worth the trouble 😉

Of course it's worth it

Where should I put screenshots from a Chromebook, @IzzySoft?
Thanks for this helpful snippet! 👍

I don't know of a specific place for that. If there is none, I'd take the "closest match" – which probably would be the tenInchScreenshots. Unless that's filled already with, well, ten inch screenshots. Then there'd probably be no place that would be used automatically, but you could create your own if needed for your own workflow. No idea what dimensions a Chromebook has, but I'd try to choose a name that would be chosen by the Fastlane people as well, i.e. trying to deduce from existing names – like fourteenInchScreenshots, desktopScreenshots or, last resort, chromebookScreenshots (though I'd feel the last one a bit too specific to be "generically useful"). Fastlane tooling should simply ignore it then AFAIK (as would F-Droid), but you could use it.

In this snippet, the Triple-T one, and the IzzyOnDroid Fastlane Documentation it says, concerning the app icon, 'useful e.g. for "service apps" containing none'.

This sounds, to me, very much as if the app icon doesn't have to be provided for apps that do contain an icon. I believe that this was the case in the past, but is no longer. Now, at least for F-Droid Main, the only way to provide an icon is in the Fastlane or Triple-T metadata.

If my understanding is correct, what do you think about updating these two snippets and the docs in this regard?

I regularly see people in fdroiddata and rfp that set up Fastlane or Triple-T according to these snippets, but don't include the icon and I suspect this is why.

The snippet here won't be updated anymore; it's mostly kept for discussion. The documentation linked at its top will be kept up-to-date though.

fdroidserver did extract the icon if it was PNG. Has that changed? Can you make sure? If not, I'd at least mark it as "highly recommended". To my knowledge, icon extraction only failed if there was no PNG icon, as there was no code implemented into fdroidserver to convert the XML icon (which in fact might be a bit tricky without depending on more dependencies).

I regularly see people in fdroiddata and rfp that set up Fastlane or Triple-T according to these snippets, but don't include the icon and I suspect this is why.

I saw one case where the dev explicitly pointed to that as a reason, yes. Was hoping someone would clarify there (whether fdroidserver no longer extracts them at all), but that didn't happen. If you could check and give me the details, I'd see to integrate that accordingly of course. Thanks!

com.unicornsonlsd.finamp in F-Droid Main doesn't have an icon and it seems that it includes PNG icons? If that is what is meant by including a PNG icon.

Given that this patch was merged and this one committed a little later, I feel like fdroidserver no longer extracts PNG icons.

If you want harder reason for assumption that this is the case, I suppose pinging someone who should know makes sense.

com.unicornsonlsd.finamp in F-Droid Main doesn't have an icon and it seems that it includes PNG icons?

Multiple. Look inside the mipmap*/ directories and watch out for ic_launcher.png.

I feel like fdroidserver no longer extracts PNG icons.

Then you might need to open an issue with fdroidserver, as it should extract app icons. And btw, the commits you've linked to rather suggest fdroidserver is supposed to handle icons well: "app icon; mandatory if your app doesn't include any png icon" was replaced by simply "app icon" (so no longer "mandatory").

If you want harder reason for assumption that this is the case, I suppose pinging someone who should know makes sense.

Feel free to do so – but preferably not here (this snippet is about fastlane structure, not about how fdroidserver works or is supposed to work, sorry). But take a look at the documentation, which I've already updated – marking the icon as "strongly recommended". Thanks for your suggestion!

fdroidserver currently does not extract icons: https://gitlab.com/fdroid/fdroidserver/-/issues/1257#note_2336684131

See my link above. I've been told the condition at the linked code is not handling it properly. And again, this snippet is not about fdroidserver, but about fastlane. And as I wrote, the IzzyOnDroid Fastlane Documentation has this updated already (marking the icon as recommended).

Sorry for only getting back to you now.

My impression was that if I confirmed that fdroidserver currently does not extract app icons, you would update the snippet. It seems I misunderstood you a little :)

And btw, the commits you've linked to rather suggest fdroidserver is supposed to handle icons well

I felt like they suggest that fdroidserver no longer extracts PNG icons as https://gitlab.com/fdroid/fdroid-website/-/commit/86360a901540deee7f543870063f9417df4484d8 adds a bullet point saying "It is the only way to provide images, such as the app icon or screenshots".

But take a look at the documentation, which I've already updated – marking the icon as "strongly recommended". Thanks for your suggestion!

Thanks! Though I feel like "recommended especially for apps containing none" still sounds like there's no need if the app contains an icon.

Sorry if this seems silly, but I'm truly not sure: why are you no interested in removing the useful e.g. for "service apps" containing none from this snippet?

this snippet is not about fdroidserver, but about fastlane

Wouldn't that suggest the useful e.g. for "service apps" containing none should be removed? I assume it was added because fdroiserver used to extract the app icon, as the Fastlane docs don't seem to mention anything along these lines: https://docs.fastlane.tools/actions/supply/#images-and-screenshots

Sorry again for taking so long to get back to you and thanks for taking the time!