feat(android): lower minSdk to 25 for Android 7.1.1 devices #1125

Merged
chris merged 3 commits from ux-android-minsdk into main 2026-10-11 21:50:13 +02:00
Owner

What changed

Lowers minSdk from 29 → 25 so the app installs on an older family phone stuck on Android 7.1.1 (API 25). The daily device (Galaxy Tab S5e, API 30) is unaffected. Three platform boundaries get explicit handling rather than being assumed away:

Desugaring (java.time is API 26+)

The viewer date bar, day-sectioned timeline, and search year filter all use java.time (Instant, OffsetDateTime, LocalDate, DateTimeFormatter, DateTimeParseException). At minSdk 25 that needs core-library desugaring, now enabled on :app (isCoreLibraryDesugaringEnabled = true + coreLibraryDesugaring(libs.desugar.jdk.libs)).

  • Artifact: com.android.tools:desugar_jdk_libs:2.1.5 (standard, not _nio). 2.1.5 is the latest release per Google's maven-metadata.xml. I picked the standard artifact over desugar_jdk_libs_nio because the NIO variant's only extra surface is java.nio.file, which nothing in the app imports — the standard build backports java.time fully and keeps the dex footprint smaller. Compatible with AGP 9.4.1 / Java 17.
  • :core is plain kotlin-jvm and uses no java.time, so only :app needs desugaring (verified by grep across core/src).

Save-to-MediaStore: version-gated write path

  • API 29+ (Q and up): unchanged — MediaStore insert into Pictures/Memories with IS_PENDING, no runtime permission.
  • API 25–28: legacy provider path. The row is placed by absolute path under the public Pictures/Memories directory (there is no RELATIVE_PATH and no IS_PENDING column pre-Q). The viewer requests WRITE_EXTERNAL_STORAGE on first save via ActivityResultContracts.RequestPermission; the pending save is parked and resumed on a grant. Denial → friendly localized snackbar (de/da/en) and the save stays resumable — never a crash or a dead end. Manifest declares the permission with android:maxSdkVersion="28" so the dialog never appears on Q+.
  • AndroidMediaDownloader.insertPending → insertEntry branches on SDK; the post-write IS_PENDING = 0 update is skipped below Q (no column to clear).

Scanner IS_PENDING predicate

AndroidMediaStoreScanner's selection drops the is_pending = 0 predicate below Q — the constant resolves everywhere (it is a plain string) but the column does not exist pre-Q, so including it would fail the query rather than merely filter.

Notifications

Checked BackupWorker and the whole tree: the app posts no notifications, so notification-channel work is correctly out of scope and none was added.

Gating design

Every SDK-dependent decision lives in a new pure object, dev.memories.android.storage.StorageCompat, as a function of the SDK number (usesScopedStorage, needsWritePermission, savePermission, scanSelection, insertValues, completionValues). This keeps both branches unit-testable without a device and gives the scanner, downloader, and viewer a single source of truth.

Trade-offs (accepted)

Trade-off Where
One-time WRITE_EXTERNAL_STORAGE dialog on first save API 25–28
No system dark mode below Q — app stays light API 25–28
Potentially slower UX on old hardware API 25–28

No functional degradation beyond these was found, so no new KNOWN_ISSUES entry was added.

Test matrix

./gradlew :app:testDebugUnitTest :app:assembleDebug → 309 tests, 0 failures, 0 skipped.

Suite Runner SDKs Cases
StorageCompatTest plain JVM explicit 25, 28, 29, 35 4 — branching, scan selection, permission decision
StorageCompatRobolectricTest Robolectric @Config(sdk=[25, 29]) 25 and 29 14 — real Build.VERSION.SDK_INT wiring + ContentValues builders

The Robolectric suite replays the policy through the real Build.VERSION.SDK_INT (what the scanner/downloader read on a device), catching a mis-wired source of truth that pure arithmetic would miss. ContentValues assertions live there because put is a framework method and is not mocked on the plain JVM.

Lint

./gradlew :app:lintDebug → 18 errors, all pre-existing and none minSdk-related:

  • 8 × UnsafeOptInUsageError + 7 × LocalContextGetResourceValueCall + 1 × MissingTranslation = ISSUE-119 (viewer PRs, documented).
  • 2 × MissingQuantity from the people-lane plurals already on main.

Zero NewApi / InlinedApi / UnusedRequiresPermission errors — the actual minSdk-25 check. lintDebug is not a CI gate (workflow runs only :app:testDebugUnitTest + :app:assembleDebug, both green).

Version

versionCode 10 → 11, versionName 0.1.9 → 0.2.0, following the changelog-comment convention in app/build.gradle.kts.

Risks

  • Legacy save path is untested on a real API 25–28 device — covered by Robolectric at the policy/ContentValues level, but the actual MediaStore write + permission dialog needs a device smoke test before relying on it.
  • The READ_EXTERNAL_STORAGE read path (backup/scanner) still has no runtime permission request anywhere — pre-existing behavior, identical on 25–28 as on 29–32, unchanged by this PR and out of scope here.
## What changed Lowers `minSdk` from **29 → 25** so the app installs on an older family phone stuck on Android 7.1.1 (API 25). The daily device (Galaxy Tab S5e, API 30) is unaffected. Three platform boundaries get explicit handling rather than being assumed away: ### Desugaring (java.time is API 26+) The viewer date bar, day-sectioned timeline, and search year filter all use `java.time` (`Instant`, `OffsetDateTime`, `LocalDate`, `DateTimeFormatter`, `DateTimeParseException`). At minSdk 25 that needs core-library desugaring, now enabled on `:app` (`isCoreLibraryDesugaringEnabled = true` + `coreLibraryDesugaring(libs.desugar.jdk.libs)`). - **Artifact: `com.android.tools:desugar_jdk_libs:2.1.5`** (standard, not `_nio`). 2.1.5 is the latest release per Google's `maven-metadata.xml`. I picked the **standard** artifact over `desugar_jdk_libs_nio` because the NIO variant's only extra surface is `java.nio.file`, which nothing in the app imports — the standard build backports `java.time` fully and keeps the dex footprint smaller. Compatible with AGP 9.4.1 / Java 17. - `:core` is plain `kotlin-jvm` and uses **no** `java.time`, so only `:app` needs desugaring (verified by grep across `core/src`). ### Save-to-MediaStore: version-gated write path - **API 29+ (Q and up):** unchanged — MediaStore insert into `Pictures/Memories` with `IS_PENDING`, no runtime permission. - **API 25–28:** legacy provider path. The row is placed by **absolute path** under the public `Pictures/Memories` directory (there is no `RELATIVE_PATH` and no `IS_PENDING` column pre-Q). The viewer requests `WRITE_EXTERNAL_STORAGE` on first save via `ActivityResultContracts.RequestPermission`; the pending save is parked and resumed on a grant. **Denial → friendly localized snackbar** (de/da/en) and the save stays resumable — never a crash or a dead end. Manifest declares the permission with `android:maxSdkVersion="28"` so the dialog never appears on Q+. - `AndroidMediaDownloader.insertPending` → `insertEntry` branches on SDK; the post-write `IS_PENDING = 0` update is skipped below Q (no column to clear). ### Scanner IS_PENDING predicate `AndroidMediaStoreScanner`'s selection drops the `is_pending = 0` predicate below Q — the constant resolves everywhere (it is a plain string) but the column does not exist pre-Q, so including it would fail the query rather than merely filter. ### Notifications Checked `BackupWorker` and the whole tree: **the app posts no notifications**, so notification-channel work is correctly out of scope and none was added. ## Gating design Every SDK-dependent decision lives in a new pure object, `dev.memories.android.storage.StorageCompat`, as a function of the SDK number (`usesScopedStorage`, `needsWritePermission`, `savePermission`, `scanSelection`, `insertValues`, `completionValues`). This keeps both branches unit-testable without a device and gives the scanner, downloader, and viewer a single source of truth. ## Trade-offs (accepted) | Trade-off | Where | |---|---| | One-time `WRITE_EXTERNAL_STORAGE` dialog on first save | API 25–28 | | No system dark mode below Q — app stays light | API 25–28 | | Potentially slower UX on old hardware | API 25–28 | No functional degradation beyond these was found, so **no new KNOWN_ISSUES entry** was added. ## Test matrix `./gradlew :app:testDebugUnitTest :app:assembleDebug` → **309 tests, 0 failures, 0 skipped.** | Suite | Runner | SDKs | Cases | |---|---|---|---| | `StorageCompatTest` | plain JVM | explicit `25, 28, 29, 35` | 4 — branching, scan selection, permission decision | | `StorageCompatRobolectricTest` | Robolectric `@Config(sdk=[25, 29])` | 25 **and** 29 | 14 — real `Build.VERSION.SDK_INT` wiring + `ContentValues` builders | The Robolectric suite replays the policy through the real `Build.VERSION.SDK_INT` (what the scanner/downloader read on a device), catching a mis-wired source of truth that pure arithmetic would miss. `ContentValues` assertions live there because `put` is a framework method and is not mocked on the plain JVM. ## Lint `./gradlew :app:lintDebug` → 18 errors, **all pre-existing** and none minSdk-related: - 8 × `UnsafeOptInUsageError` + 7 × `LocalContextGetResourceValueCall` + 1 × `MissingTranslation` = ISSUE-119 (viewer PRs, documented). - 2 × `MissingQuantity` from the people-lane plurals already on `main`. **Zero** `NewApi` / `InlinedApi` / `UnusedRequiresPermission` errors — the actual minSdk-25 check. `lintDebug` is not a CI gate (workflow runs only `:app:testDebugUnitTest` + `:app:assembleDebug`, both green). ## Version `versionCode 10 → 11`, `versionName 0.1.9 → 0.2.0`, following the changelog-comment convention in `app/build.gradle.kts`. ## Risks - **Legacy save path is untested on a real API 25–28 device** — covered by Robolectric at the policy/`ContentValues` level, but the actual MediaStore write + permission dialog needs a device smoke test before relying on it. - The `READ_EXTERNAL_STORAGE` **read** path (backup/scanner) still has no runtime permission request anywhere — pre-existing behavior, identical on 25–28 as on 29–32, unchanged by this PR and out of scope here.
The app installs on an older family phone stuck on Android 7.1.1 (API 25)
while staying unchanged on the Galaxy Tab S5e (API 30) daily device.

minSdk 29 -> 25 straddles three platform boundaries, each handled
explicitly rather than assumed:

- java.time (Instant/OffsetDateTime/LocalDate/DateTimeFormatter) is API
  26+, so core-library desugaring is enabled on :app with
  desugar_jdk_libs 2.1.5. The standard artifact is used, not the _nio
  variant: nothing in the app touches java.nio.file, which is the only
  addition the _nio build makes. :core is plain kotlin-jvm and uses no
  java.time, so it needs no desugaring.

- Saving into the shared gallery: Q and up keep the existing IS_PENDING
  MediaStore path (no runtime permission). 25-28 write through the
  legacy provider, placing the row by absolute path under
  Pictures/Memories with no IS_PENDING column to set, and the viewer
  asks for WRITE_EXTERNAL_STORAGE on first save via
  ActivityResultContracts.RequestPermission. A denial shows a friendly
  localized snackbar and leaves the save resumable — never a crash or a
  dead end. The permission is declared with maxSdkVersion=28.

- The device scanner's IS_PENDING predicate is dropped below Q, where
  the column does not exist and the query would fail rather than filter.

StorageCompat holds every SDK-dependent decision as a pure function of
the SDK number so both sides are unit-testable without a device.

Trade-offs accepted up front: the WRITE dialog appears once on 25-28,
system dark mode stays off below Q (app runs light), and the old
hardware may feel slower. Version bumps to 0.2.0 / versionCode 11.
test(android): cover the storage policy at SDK 25 and 29
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 4s
Build and Deploy / Android unit tests and debug APK (push) Successful in 7m33s
eb3cde8ab3
Pins both sides of the scoped-storage boundary so a future edit cannot
quietly drop the legacy path.

StorageCompatTest (plain JVM) checks the branching against explicit SDK
numbers: the 25-28 band is the only one needing WRITE_EXTERNAL_STORAGE,
the scan drops the is-pending predicate below Q, and the permission
decision reads the grant only when one is required.

StorageCompatRobolectricTest (@Config(sdk=[25, 29])) replays the same
decisions through the real Build.VERSION.SDK_INT that the scanner and
downloader read on a device, catching a mis-wired source of truth that
pure arithmetic would miss. It also builds the insert/completion
ContentValues, which are Android framework types and cannot run on the
plain JVM, so those assertions live here.

7 methods x 2 SDK levels = 14 Robolectric cases; 309 tests green.
docs: track missing READ_EXTERNAL_STORAGE runtime request (ISSUE-130)
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 4s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 6s
Build and Deploy / Android unit tests and debug APK (push) Successful in 2m19s
7097a490ae
chris merged commit cbb8cd1eda into main 2026-10-11 21:50:13 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1125
No description provided.