Merge pull request 'Document the APK filename/versionCode naming contract' (#14) from apk-versioncode-naming-contract into main

Reviewed-on: #14

README.md

@@ -350,6 +350,28 @@ collision; it prevents the collision from silently corrupting the repo.
 Skipped entirely for a plain `--index-only` invocation (below), since that
 pass can never upload a `*.apk` in the first place.
 
+### APK filenames must carry the versionCode (fdroid-repo-ci#13)
+
+That guard is correct -- a published versionCode's artifact has to stay
+immutable -- but it has a consequence nothing else here states: **the
+filename has to carry the versionCode**, or the guard permits exactly one
+publish into a prefix, ever. `publish.sh` checks the destination *key*, not
+the artifact's contents, so a build that always emits the same filename
+collides with itself on its second run regardless of what actually changed
+inside the APK.
+
+Name the APK `<applicationId>_<versionCode>.apk` -- F-Droid's own
+convention, and what `fdroid update` expects -- before handing it to
+`fdroid-update.sh`/`publish.sh`. Concretely: Flutter's
+`flutter build apk` always emits `app-<flavor>-release.apk`, independent of
+`--build-number`, so a consumer that publishes that path unchanged gets a
+successful first publish and then a permanent refusal on every publish
+after it -- exactly what happened to weblib-viewer (weblib-viewer#29) before
+it started renaming the artifact to `<applicationId>_<versionCode>.apk`
+ahead of this step. The failure only shows up on the *second* publish, long
+after the integration looks finished, and reads like a bucket-state problem
+(see the error text below) rather than the naming contract it actually is.
+
 ### `--files-only` and `--index-only`
 
 The two passes can also be run as two separate invocations: