calendula/docs/fdroid-official

Official F-Droid submission (draft)

Goal: publish Calendula to the official F-Droid repo alongside the self-hosted repo, as one app — same signed binary in both channels, so existing self-hosted users migrate with no reinstall and no data loss.

This folder holds the draft fdroiddata recipe. Nothing here is submitted yet. The self-hosted pipeline (../../fdroid-metadata/, .gitea/workflows/release.yaml) is unaffected by these files.

Publishing model: reproducible build + developer-signed binary

F-Droid builds Calendula from source on its buildserver, then verifies the output is byte-for-byte identical to our signed APK (fetched via the Binaries URL). On a match it publishes our binary, signed with our key — identified by AllowedAPKSigningKeys. Result: official and self-hosted both carry the same signature. If a build ever fails to match, F-Droid simply skips that version (fails safe — no bad publish).

Verification status (2026-06-21)

• ✅ Run-to-run reproducible — v2.7.0 built twice from a clean worktree (R8 minify + resource-shrink, build cache off) → byte-for-byte identical (sha256 568c944a…).
• ✅ Cross-JDK reproducible — rebuilt with JDK 17 and JDK 21 → identical APK. JDK version is not a sensitivity, so it need not be pinned.
• ✅ Tag self-consistent — committed versionCode/versionName already equal the tag-derived values, so F-Droid building the tag as-is matches the CI-published binary (CI's sed substitution is a no-op).
• ✅ App signing cert SHA-256 extracted from published APKs (identical across v1.0.0 / v2.0.0 / v2.4.0): 5cdaee8e…. No keystore needed.
• ✅ Eligibility — MIT, 100% FOSS deps (no Play Services / Firebase / analytics / billing), no INTERNET permission, no native code.
• ✅ End-to-end reproducible vs the DISTRIBUTED binary — built tag v2.7.1 from source and compared against the published calendula_v2.7.1.apk: every app entry (dex / resources / assets / manifest) byte-identical. The only difference was META-INF/version-control-info.textproto (AGP's git metadata, env-dependent). Fixed with vcsInfo { include = false } on the release build; re-validated → 0 non-signature differences. Takes effect from the first release built after that change — submit the recipe starting at that version (v2.7.1 and earlier still embed the textproto and won't verify).
• ⚠️ Not yet proven: cross-host / fixed-build-path reproducibility on F-Droid's buildserver (low risk for a no-NDK pure-JVM app; with vcsInfo disabled, the env-dependent field is gone; F-Droid confirms at review).
• ✅ Buildserver toolchain supported (checked 2026-06-21):
  • Gradle 9.5.1 is in F-Droid's gradle-transparency-log (checksums.json) with a verified sha256, so gradlew.py will download + verify + run it.
  • AGP 9.2 is in gradlew.py's MIN_GRADLE_VERSION map (9.2 -> 9.4.1).
  • JDK 17 is standard on the buildserver (AGP 9.2 requires exactly 17).
  • build-tools 36.0.0 / android-37: not statically preinstalled (baseline stops at 33), but provision-android-sdk makes $ANDROID_HOME/build-tools and /platforms group-writable so AGP/Gradle install newer ones on demand.

Before submitting — checklist

1. Confirm the Binaries URL is publicly reachable and stable long-term, e.g. https://apps.dev.jeanlucmakiola.de/dev/fdroid/repo/calendula_v2.7.0.apk resolves to the dev-signed APK. F-Droid re-fetches it on every build.
2. Confirm F-Droid's buildserver supports the toolchain (see timing risk).
3. (Recommended) Reproduce one published release end-to-end: build the tag from source, strip signatures, and diff against the downloaded calendula_v<ver>.apk to confirm the from-source build matches the distributed binary — not just another local build.

Submission steps (fdroiddata, GitLab)

1. Fork https://gitlab.com/fdroid/fdroiddata.
2. Copy de.jeanlucmakiola.calendula.yml to metadata/ in the fork.
3. Test locally with fdroid build -v de.jeanlucmakiola.calendula and fdroid lint de.jeanlucmakiola.calendula (and fdroid readmeta).
4. Open a Merge Request. Initial review can take weeks to months; the self-hosted repo keeps serving in the meantime, so there's no rush.

Listing metadata (descriptions, screenshots, icon)

These are not in the recipe .yml. F-Droid's fdroid update harvests them automatically from the fastlane tree in the app's source repo:

fastlane/metadata/android/<locale>/
  short_description.txt   full_description.txt   title.txt
  images/icon.png         images/phoneScreenshots/*.png
  changelogs/<versionCode>.txt   (optional, per release)

This is the single source of truth: en-US + de-DE already exist there, and the self-hosted repo is generated from the same tree at release time via scripts/fastlane_to_fdroid_localized.sh. Nothing extra to add to fdroiddata — F-Droid picks the listing up from source. (Screenshots may not be committed to the fdroiddata repo anyway, so the source-tree fastlane layout is required.)

Per-version changelogs: the self-hosted release workflow generates changelogs/<versionCode>.txt at release time. For the official repo to show a changelog, that file must be committed into fastlane/metadata/android/<locale>/changelogs/ at the tagged commit — wire this into the release/version-bump step, or accept no in-client changelog for the official listing initially.