QSfera/Android/docs/argus-rollout-policy.md

QSfera Android Argus Rollout Policy

Sources

• Android update requirement: Android Developers says an update must use the same application ID and the same signing certificate as the installed app, unless it contains a valid proof-of-rotation: https://developer.android.com/google/play/app-updates.
• QSfera update implementation: Android/qsferaApp/src/main/java/eu/qsfera/android/presentation/settings/update/AppUpdateManager.kt.
• QSfera Android version and release signing env names: Android/qsferaApp/build.gradle.
• Current Argus release and certificate facts verified for this production-readiness pass: PRODUCTION_READINESS.md, section Android Argus Publication Check.

Policy

• Stable Argus releases for qsfera-mobile must keep the same package name and production signing certificate after the first production-signed 1.3.11 / 39 release.
• The in-app updater must not bypass certificate mismatch. AppUpdateManager validates package name, monotonically newer versionCode, Argus androidVersionCode, and signer digest before starting Android package installation.
• A client installed from the debug-signed 1.3.5 / 33 Argus APK cannot be moved to the current production-signed stable APK (1.3.12 / 40 as of 2026-06-10) by the in-app updater because the signer digest check intentionally fails.
• For debug-signed 1.3.5 installs, the supported migration path is: back up unsynced local files, uninstall the debug-signed build, then install the current stable QSfera APK from Argus.
• On certificate mismatch, the Android app must show an explicit reinstall-required dialog instead of a generic update error.

Release Checklist

1. Build the stable APK with the same release key material through QSFERA_RELEASE_KEYSTORE, QSFERA_RELEASE_KEYSTORE_PASSWORD, QSFERA_RELEASE_KEY_ALIAS, and QSFERA_RELEASE_KEY_PASSWORD.
2. Prepare Argus publication only from a clean release branch whose HEAD matches its upstream; Android/scripts/prepare-argus-publication.ps1 enforces this by default and records repository root, branch, upstream, commit, and verification time in argus-publication.json. When the Android checkout is used from the pushed QSfera.git monorepo, run it from Android/ with -GitProvenanceRoot ...
3. Verify the APK certificate before upload with apksigner verify --print-certs.
4. Publish to Argus only after certificate, package name, version code, SHA-256, and git provenance checks pass.
5. Verify the published manifest and download with scripts/verify-production-state.ps1 -VerifyAndroidDownload from the repository root.