✨ feat: F-Droid publishing readiness (#4)

- Tag-driven version derivation in buildSrc/Version.kt (8 unit tests, TDD)
  replaces env-var-injected CalVer; F-Droid can now reproduce a build
  from a tag.
- CI workflow drops BUILD_DATE / GITHUB_RUN_NUMBER injection; uses
  fetch-tags: true on actions/checkout so git describe works.
- featureGraphic.png (1024x500) for the F-Droid listing.
- Changelog renamed to 26050830.txt to match v2026.05.08.30 versionCode.
- CONTRIBUTING.md documents 🔧 chore: and 🚧.
- docs/release.md documents the local fdroid build --server repro check.

Closes #5 (R8 follow-up tracked separately).

Author: vitofico

.github/workflows/android-ci.yaml

@@ -41,6 +41,9 @@ jobs:
       version: ${{ steps.version.outputs.version }}
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
       - uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4
         with:
           distribution: temurin
@@ -52,8 +55,14 @@ jobs:
       - id: version
         name: Compute version
         run: |
-          BUILD_DATE=$(date -u +%Y-%m-%d)
-          VERSION="${BUILD_DATE//-/.}.${GITHUB_RUN_NUMBER}"
+          # Match what app/build.gradle.kts derives from the same checkout.
+          # Tags are pulled by checkout's fetch-tags: true; verify here.
+          if ! git describe --tags --match 'v*' --abbrev=0 >/dev/null 2>&1; then
+            echo "::error::No matching v* tag in history. Build will fail."
+            git tag -l 'v*' | head
+            exit 1
+          fi
+          VERSION=$(git describe --tags --match 'v*' --always | sed 's/^v//')
           echo "VERSION_NAME=$VERSION" >> "$GITHUB_ENV"
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "Building version $VERSION"
@@ -83,6 +92,9 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
       - uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4
         with:
           distribution: temurin

CONTRIBUTING.md

@@ -76,12 +76,14 @@ Gitmoji + conventional commits. Examples:
 :memo: docs: clarify identity precedence
 :white_check_mark: test: cover the alias-merge transaction
 :construction_worker: ci: pin actions to commit SHAs
+:wrench: chore: bump renovate config
 ```
 
 Common gitmoji used here: `:sparkles:` (feat), `:bug:` (fix),
 `:memo:` (docs), `:white_check_mark:` (tests), `:construction_worker:`
-(CI), `:art:` (refactor/style), `:fire:` (removals),
-`:lock:` (security), `:page_facing_up:` (legal/license).
+(CI), `:wrench:` (chore), `:construction:` (scaffolding / WIP),
+`:art:` (refactor/style), `:fire:` (removals), `:lock:` (security),
+`:page_facing_up:` (legal/license).
 
 ## Identity rules — Kotlin / Python parity
 

app/build.gradle.kts

@@ -1,28 +1,29 @@
-import java.time.LocalDate
-import java.time.format.DateTimeFormatter
-
 plugins {
     alias(libs.plugins.android.application)
     alias(libs.plugins.kotlin.android)
     alias(libs.plugins.kotlin.compose)
     alias(libs.plugins.aboutlibraries)
 }
 
-// CalVer: versionName = YYYY.MM.DD[.<run>], versionCode = YYMMDD*100 + run%100.
-// BUILD_DATE (YYYY-MM-DD) and GITHUB_RUN_NUMBER are set by CI; local builds fall
-// back to today's date and run 0.
-val buildDate: LocalDate =
-    System.getenv("BUILD_DATE")?.takeIf { it.isNotBlank() }
-        ?.let(LocalDate::parse)
-        ?: LocalDate.now()
-val buildRun: Int = System.getenv("GITHUB_RUN_NUMBER")?.toIntOrNull() ?: 0
-val calverName: String = buildString {
-    append(buildDate.format(DateTimeFormatter.ofPattern("yyyy.MM.dd")))
-    if (buildRun > 0) append(".$buildRun")
-}
-val calverCode: Int =
-    buildDate.format(DateTimeFormatter.ofPattern("yyMMdd")).toInt() * 100 +
-        (buildRun % 100)
+// Tag-driven CalVer. The build reads `git describe --tags --match 'v*'`
+// and parses it via buildSrc/Version.kt. Set QUIRE_VERSION_FALLBACK
+// (e.g. "2026.05.08.29") if building from a shallow clone with no tags.
+fun gitDescribe(): String =
+    try {
+        val process = ProcessBuilder("git", "describe", "--tags", "--match", "v*", "--always")
+            .directory(rootDir)
+            .redirectErrorStream(true)
+            .start()
+        val output = process.inputStream.bufferedReader().readText().trim()
+        if (process.waitFor() == 0) output else ""
+    } catch (_: Exception) {
+        ""
+    }
+
+val versionInfo = Version.fromGitDescribe(
+    output = gitDescribe(),
+    fallback = System.getenv("QUIRE_VERSION_FALLBACK")
+)
 
 android {
     namespace = "io.theficos.quire"
@@ -31,8 +32,8 @@ android {
         applicationId = "io.theficos.quire"
         minSdk = 26
         targetSdk = 34
-        versionCode = calverCode
-        versionName = calverName
+        versionCode = versionInfo.code
+        versionName = versionInfo.name
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
     }
     compileOptions {

buildSrc/build.gradle.kts

@@ -0,0 +1,17 @@
+plugins {
+    `kotlin-dsl`
+}
+
+repositories {
+    mavenCentral()
+    google()
+}
+
+dependencies {
+    testImplementation("junit:junit:4.13.2")
+    testImplementation("com.google.truth:truth:1.4.4")
+}
+
+tasks.test {
+    useJUnit()
+}

buildSrc/src/main/kotlin/Version.kt

@@ -0,0 +1,43 @@
+data class VersionInfo(val name: String, val code: Int)
+
+object Version {
+
+    private val EXACT = Regex("""^v(\d{4})\.(\d{2})\.(\d{2})\.(\d+)$""")
+    private val POST_TAG = Regex("""^v(\d{4})\.(\d{2})\.(\d{2})\.(\d+)-(\d+)-(g[0-9a-f]+)$""")
+
+    fun fromGitDescribe(output: String, fallback: String? = null): VersionInfo {
+        val trimmed = output.trim()
+
+        EXACT.matchEntire(trimmed)?.let { m ->
+            val (yyyy, mm, dd, run) = m.destructured
+            return VersionInfo(
+                name = "$yyyy.$mm.$dd.$run",
+                code = computeCode(yyyy, mm, dd, run)
+            )
+        }
+
+        POST_TAG.matchEntire(trimmed)?.let { m ->
+            val (yyyy, mm, dd, run, dist, sha) = m.destructured
+            return VersionInfo(
+                name = "$yyyy.$mm.$dd.$run.dev$dist+$sha",
+                code = computeCode(yyyy, mm, dd, run)
+            )
+        }
+
+        if (fallback != null) {
+            return fromGitDescribe("v$fallback")
+        }
+
+        error(
+            "Could not derive version from git describe output: '$trimmed'. " +
+                "Set QUIRE_VERSION_FALLBACK env var to a tag name like '2026.05.08.29' " +
+                "(without leading 'v'), or build from a checkout that has at least one " +
+                "matching tag in history."
+        )
+    }
+
+    private fun computeCode(yyyy: String, mm: String, dd: String, run: String): Int {
+        val yyMMdd = (yyyy.takeLast(2) + mm + dd).toInt()
+        return yyMMdd * 100 + (run.toInt() % 100)
+    }
+}

buildSrc/src/test/kotlin/VersionTest.kt

@@ -0,0 +1,63 @@
+import com.google.common.truth.Truth.assertThat
+import org.junit.Test
+import org.junit.Assert.assertThrows
+
+class VersionTest {
+
+    @Test
+    fun exactTag_parsesNameAndCode() {
+        val result = Version.fromGitDescribe("v2026.05.08.29")
+        assertThat(result.name).isEqualTo("2026.05.08.29")
+        assertThat(result.code).isEqualTo(26050829)
+    }
+
+    @Test
+    fun exactTag_yearEndRollover() {
+        val result = Version.fromGitDescribe("v2026.12.31.99")
+        assertThat(result.name).isEqualTo("2026.12.31.99")
+        assertThat(result.code).isEqualTo(26123199)
+    }
+
+    @Test
+    fun exactTag_runOver99_wrapsModulo() {
+        // Run-number byte is mod-100 to fit in Int safely; documented in spec.
+        val result = Version.fromGitDescribe("v2026.05.08.103")
+        assertThat(result.name).isEqualTo("2026.05.08.103")
+        assertThat(result.code).isEqualTo(26050803)
+    }
+
+    @Test
+    fun postTag_appendsDevSuffix_keepsBaseVersionCode() {
+        val result = Version.fromGitDescribe("v2026.05.08.29-3-gabcdef0")
+        assertThat(result.name).isEqualTo("2026.05.08.29.dev3+gabcdef0")
+        assertThat(result.code).isEqualTo(26050829)
+    }
+
+    @Test
+    fun postTag_trimsLeadingTrailingWhitespace() {
+        val result = Version.fromGitDescribe("  v2026.05.08.29-1-gdeadbee\n")
+        assertThat(result.name).isEqualTo("2026.05.08.29.dev1+gdeadbee")
+    }
+
+    @Test
+    fun bareSha_withFallback_treatsFallbackAsExactTag() {
+        val result = Version.fromGitDescribe("abcdef0", fallback = "2026.05.08.29")
+        assertThat(result.name).isEqualTo("2026.05.08.29")
+        assertThat(result.code).isEqualTo(26050829)
+    }
+
+    @Test
+    fun bareSha_noFallback_throwsWithGuidance() {
+        val ex = assertThrows(IllegalStateException::class.java) {
+            Version.fromGitDescribe("abcdef0")
+        }
+        assertThat(ex).hasMessageThat().contains("QUIRE_VERSION_FALLBACK")
+    }
+
+    @Test
+    fun emptyOutput_noFallback_throws() {
+        assertThrows(IllegalStateException::class.java) {
+            Version.fromGitDescribe("")
+        }
+    }
+}

docs/release.md

@@ -59,3 +59,56 @@ scripts/dgradle :app:assembleRelease
 
 If the env vars are unset, `:app:assembleRelease` falls back to
 debug-signed.
+
+## Reproducibility check before submitting to F-Droid
+
+F-Droid's builder rebuilds every release from source and compares the
+output to the signed APK in your GitHub Release. If the contents
+differ, F-Droid won't publish. Run the same check locally before
+submitting the recipe MR.
+
+```sh
+# In an fdroiddata clone (https://gitlab.com/fdroid/fdroiddata),
+# with fdroidserver installed:
+cd ~/src/fdroiddata
+fdroid lint io.theficos.quire
+fdroid readmeta
+fdroid rewritemeta io.theficos.quire
+fdroid build --server -v -l io.theficos.quire
+```
+
+The `--server` flag spins fdroidserver's reproducible build VM
+(headless VirtualBox by default; podman backend also supported). On
+success, the unsigned APK lands in
+`~/src/fdroiddata/unsigned/io.theficos.quire_<versionCode>.apk`.
+
+Compare it to your signed release APK:
+
+```sh
+# Strip signatures from both, then diff the contents.
+cd /tmp && mkdir cmp && cd cmp
+unzip -q ~/src/fdroiddata/unsigned/io.theficos.quire_*.apk -d a
+unzip -q ~/Downloads/app-release.apk -d b
+rm -rf a/META-INF b/META-INF       # signatures differ by design
+diff -r a b && echo "REPRODUCIBLE"
+```
+
+If `diff` reports no differences, F-Droid will accept the build. If
+it reports differences in `classes*.dex`, the build is non-reproducible
+— check JDK version, AGP version, and `gradle.properties` flags in
+the fdroidserver VM vs the CI runner.
+
+If `git describe` returns nothing inside the fdroidserver VM (it does
+a non-shallow clone, but on rare runs tags might not propagate),
+set `QUIRE_VERSION_FALLBACK` in the recipe's `Builds:` block:
+
+```yaml
+Builds:
+  - versionName: 2026.05.08.30
+    versionCode: 26050830
+    commit: v2026.05.08.30
+    subdir: app
+    gradle: [ yes ]
+    env:
+      QUIRE_VERSION_FALLBACK: 2026.05.08.30
+```