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.
• Argus publication authority: G:/Repos/Marketplace/ARGUS_PUBLICATION.md.
• 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.
• Argus publication is SSH-only and must follow G:/Repos/Marketplace/ARGUS_PUBLICATION.md: copy the APK to the Pi, write metadata to /srv/argus-data/argus.db, and store package bytes under /srv/argus-data/Packages. Do not add or use HTTP /api/admin/* publication routes from this repository.
• The in-app updater must use the public read-only manifest endpoint, treat HTTP 404 as no update, compare release.version with the installed version, download ARGUS_BASE_URL + release.downloadPath, verify release.packageSizeBytes and release.sha256, and only then start Android package installation.
• The in-app updater must not bypass certificate mismatch. AppUpdateManager validates package name, newer installed APK metadata, optional Argus androidVersionCode when present, manifest version, 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.13 / 41 as of 2026-06-12) 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 local release signing material and latest Argus APK certificate with Android/scripts/verify-release-signing-material.ps1 -VerifyPublishedApk.
4. Verify the APK certificate before upload with apksigner verify --print-certs.
5. Publish to Argus only through Android/scripts/publish-release.ps1, which implements the SSH/SQLite/Data/Packages workflow from G:/Repos/Marketplace/ARGUS_PUBLICATION.md; do not publish through HTTP admin APIs.
6. Verify the published manifest and download with scripts/verify-production-state.ps1 -VerifyAndroidDownload from the repository root.