[BW-DEP-01] Execute staged latest-stable toolchain and dependency migration #42

Closed
opened 2026-09-18 08:48:18 +02:00 by alexander · 6 comments
Owner

Migrated from GitHub issue #135. Forgejo issue: #42. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links.

Classification

Build/toolchain/dependency maintenance program. This issue owns execution of the staged migration described by docs/latest-stable-upgrade-plan.md; GitHub PR #131 was the planning/tooling-preparation change and did not execute the migration.

Goal

Move BookWave toward the latest mutually compatible stable build tools, Android platform, frameworks, application/runtime libraries, test tooling and CI tooling without turning the upgrade into one unreviewable dependency bomb or weakening verification to make it pass.

gradle/libs.versions.toml remains the pinned dependency/toolchain source of truth. docs/latest-stable-upgrade-plan.md remains the detailed migration playbook and should be referenced rather than copied here.

Current compatibility gate

Re-resolve this at the start of every phase. As of 2026-09-10, accepted ADR-0011 is still material: it says BookWave stays off AGP 9 / API 37 until detekt has a stable 2.x release with the required type-resolution support, unless that ADR is explicitly superseded by a separately accepted decision. The currently published detekt 2.x line is still pre-release, so do not bypass the ADR by pinning an alpha.

Also do not assume the individually newest Gradle, AGP and Kotlin releases form a supported trio. Verify their official compatibility ranges immediately before each build-foundation phase.

Execution rules

  • No bulk dependency bomb.
  • Prefer one compatibility axis / safe phase per PR where practical.
  • Every phase starts from current main, not from a stale upgrade branch.
  • Resolve latest stable versions again immediately before implementation; version numbers in the plan are snapshots, not promises.
  • No alpha/beta/RC/EAP/preview dependencies or tooling unless separately approved.
  • “Latest stable” means the latest mutually compatible stable stack, not independently selecting versions whose compatibility ranges do not overlap.
  • Keep all direct versions pinned; dynamic versions remain forbidden.
  • Do not mix feature work into upgrade PRs unless a compatibility repair is unavoidable and narrowly documented.
  • Never disable warnings, lint, detekt/type resolution, tests, verification, schema checks or security checks merely to make an upgrade green.
  • Classpath-changing phases must verify with --rerun-tasks as required by AGENTS.md / docs/testing.md.
  • Retry ADR-0010 dependency locking at the Gradle/AGP 9 foundation step and record the result; do not weaken strict dependency verification.

Required phase-specific evidence

  • Gradle / AGP / Kotlin / KSP / quality tooling: official compatibility evidence, clean build-logic configuration, Codex/CI reproducibility, warnings-as-errors verification.
  • Android SDK / Compose / AndroidX: UI/accessibility/device validation; do not raise compileSdk/targetSdk ahead of the accepted architecture gate.
  • Room / DataStore / WorkManager: migration/persistence/process-death/background-state verification. Never modify a committed Room schema in place.
  • Media3: phone playback plus media-control surfaces and Android Auto/DHU/real-hardware verification appropriate to the changed behavior.
  • Networking/runtime: preserve BookWave's captured Audiobookshelf contracts; major OkHttp/Retrofit changes must prove auth, REST, websocket and cancellation/error behavior rather than only compiling.
  • CI / Codex / JDK / Android SDK tooling / security tools: re-probe the environment after build-tool migration instead of assuming the old JDK/runner/action combination still represents the target environment.
  • After the manual migration reaches the chosen stable frontier, add dependency-update automation so future drift is visible without allowing automatic unsafe merges.

Suggested staged sequence

Follow docs/latest-stable-upgrade-plan.md, re-splitting when compatibility evidence requires it. The conceptual order is:

  1. current-version inventory and compatibility re-probe;
  2. Gradle/AGP build foundation when ADR-0011's stable-detekt gate is satisfied or explicitly superseded;
  3. Kotlin/KSP/code-quality tooling;
  4. Android SDK/Compose/general AndroidX;
  5. persistence/background/playback libraries as separate risk-sized PRs;
  6. network/runtime libraries;
  7. visual libraries;
  8. test stack;
  9. CI/Codex/SDK/security tooling;
  10. dependency-update automation.

Do not force this sequence if current official compatibility evidence requires a narrower split. Record why any phase is moved.

Acceptance criteria

  • Each merged migration phase is independently reviewable and green under the then-current repository verification gate.
  • The final selected versions are the latest mutually compatible stable versions re-resolved during execution, not copied blindly from a dated document.
  • No accepted ADR is silently overridden.
  • Phone/device/platform/API contract evidence exists wherever JVM tests cannot prove the claim.
  • gradle/libs.versions.toml, build docs, upgrade plan status and CI/Codex provisioning agree after each relevant phase.
  • Strict dependency verification remains intact; ADR-0010 locking is re-tested at the named build-foundation point.
  • A maintenance automation exists after the migration to surface future stable dependency/tooling updates.

Governance

Do not merge any implementation PR automatically. Every phase is a separate reviewed change unless the repository's current plan explicitly justifies combining tightly coupled axes.

> Migrated from [GitHub issue #135](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/135). Forgejo issue: #42. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links. ## Classification Build/toolchain/dependency maintenance program. This issue owns **execution** of the staged migration described by `docs/latest-stable-upgrade-plan.md`; [GitHub PR #131](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/131) was the planning/tooling-preparation change and did not execute the migration. ## Goal Move BookWave toward the latest **mutually compatible stable** build tools, Android platform, frameworks, application/runtime libraries, test tooling and CI tooling without turning the upgrade into one unreviewable dependency bomb or weakening verification to make it pass. `gradle/libs.versions.toml` remains the pinned dependency/toolchain source of truth. `docs/latest-stable-upgrade-plan.md` remains the detailed migration playbook and should be referenced rather than copied here. ## Current compatibility gate Re-resolve this at the start of every phase. As of 2026-09-10, accepted ADR-0011 is still material: it says BookWave stays off AGP 9 / API 37 until detekt has a stable 2.x release with the required type-resolution support, unless that ADR is explicitly superseded by a separately accepted decision. The currently published detekt 2.x line is still pre-release, so **do not bypass the ADR by pinning an alpha**. Also do not assume the individually newest Gradle, AGP and Kotlin releases form a supported trio. Verify their official compatibility ranges immediately before each build-foundation phase. ## Execution rules - No bulk dependency bomb. - Prefer one compatibility axis / safe phase per PR where practical. - Every phase starts from current `main`, not from a stale upgrade branch. - Resolve latest stable versions again immediately before implementation; version numbers in the plan are snapshots, not promises. - No alpha/beta/RC/EAP/preview dependencies or tooling unless separately approved. - “Latest stable” means the latest **mutually compatible stable stack**, not independently selecting versions whose compatibility ranges do not overlap. - Keep all direct versions pinned; dynamic versions remain forbidden. - Do not mix feature work into upgrade PRs unless a compatibility repair is unavoidable and narrowly documented. - Never disable warnings, lint, detekt/type resolution, tests, verification, schema checks or security checks merely to make an upgrade green. - Classpath-changing phases must verify with `--rerun-tasks` as required by `AGENTS.md` / `docs/testing.md`. - Retry ADR-0010 dependency locking at the Gradle/AGP 9 foundation step and record the result; do not weaken strict dependency verification. ## Required phase-specific evidence - **Gradle / AGP / Kotlin / KSP / quality tooling:** official compatibility evidence, clean build-logic configuration, Codex/CI reproducibility, warnings-as-errors verification. - **Android SDK / Compose / AndroidX:** UI/accessibility/device validation; do not raise `compileSdk`/`targetSdk` ahead of the accepted architecture gate. - **Room / DataStore / WorkManager:** migration/persistence/process-death/background-state verification. Never modify a committed Room schema in place. - **Media3:** phone playback plus media-control surfaces and Android Auto/DHU/real-hardware verification appropriate to the changed behavior. - **Networking/runtime:** preserve BookWave's captured Audiobookshelf contracts; major OkHttp/Retrofit changes must prove auth, REST, websocket and cancellation/error behavior rather than only compiling. - **CI / Codex / JDK / Android SDK tooling / security tools:** re-probe the environment after build-tool migration instead of assuming the old JDK/runner/action combination still represents the target environment. - After the manual migration reaches the chosen stable frontier, add dependency-update automation so future drift is visible without allowing automatic unsafe merges. ## Suggested staged sequence Follow `docs/latest-stable-upgrade-plan.md`, re-splitting when compatibility evidence requires it. The conceptual order is: 1. current-version inventory and compatibility re-probe; 2. Gradle/AGP build foundation **when ADR-0011's stable-detekt gate is satisfied or explicitly superseded**; 3. Kotlin/KSP/code-quality tooling; 4. Android SDK/Compose/general AndroidX; 5. persistence/background/playback libraries as separate risk-sized PRs; 6. network/runtime libraries; 7. visual libraries; 8. test stack; 9. CI/Codex/SDK/security tooling; 10. dependency-update automation. Do not force this sequence if current official compatibility evidence requires a narrower split. Record why any phase is moved. ## Acceptance criteria - Each merged migration phase is independently reviewable and green under the then-current repository verification gate. - The final selected versions are the latest mutually compatible stable versions re-resolved during execution, not copied blindly from a dated document. - No accepted ADR is silently overridden. - Phone/device/platform/API contract evidence exists wherever JVM tests cannot prove the claim. - `gradle/libs.versions.toml`, build docs, upgrade plan status and CI/Codex provisioning agree after each relevant phase. - Strict dependency verification remains intact; ADR-0010 locking is re-tested at the named build-foundation point. - A maintenance automation exists after the migration to surface future stable dependency/tooling updates. ## Governance Do not merge any implementation PR automatically. Every phase is a separate reviewed change unless the repository's current plan explicitly justifies combining tightly coupled axes.
Author
Owner

Imported GitHub comment by @AlexanderWilhelmsenBerg, originally posted 2026-09-13T20:57:15Z. Original comment

Reopened after verifying merged GitHub PR #137 against this issue. GitHub PR #137 was explicitly Phase 0 inventory/documentation only, changed only docs/README.md and added docs/dependency-compatibility-inventory.md, changed no dependency/toolchain/SDK/CI versions, and explicitly stated that it did not close #135. The staged migration therefore remains active; no duplicate issue is being created.

> Imported GitHub comment by **@AlexanderWilhelmsenBerg**, originally posted 2026-09-13T20:57:15Z. [Original comment](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/135#issuecomment-5656087598) Reopened after verifying merged [GitHub PR #137](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/137) against this issue. [GitHub PR #137](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/137) was explicitly Phase 0 inventory/documentation only, changed only `docs/README.md` and added `docs/dependency-compatibility-inventory.md`, changed no dependency/toolchain/SDK/CI versions, and explicitly stated that it did **not** close #135. The staged migration therefore remains active; no duplicate issue is being created.
Author
Owner

Imported GitHub comment by @AlexanderWilhelmsenBerg, originally posted 2026-09-15T13:34:37Z. Original comment

Next staged slice opened as GitHub PR #161: AndroidX Activity 1.12.4 → 1.13.0. Stable 1.13.0 remains compatible with the current API-36 lane; the newer 1.14 line is prerelease and its Compose artifacts move to compileSdk 37.1, so ADR-0011 remains intact. version-control.md and the Phase-3 roadmap status are updated in the same PR. #135 remains open.

> Imported GitHub comment by **@AlexanderWilhelmsenBerg**, originally posted 2026-09-15T13:34:37Z. [Original comment](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/135#issuecomment-5681067704) Next staged slice opened as [GitHub PR #161](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/161): AndroidX Activity 1.12.4 → 1.13.0. Stable 1.13.0 remains compatible with the current API-36 lane; the newer 1.14 line is prerelease and its Compose artifacts move to compileSdk 37.1, so ADR-0011 remains intact. `version-control.md` and the Phase-3 roadmap status are updated in the same PR. #135 remains open.
Author
Owner

Imported GitHub comment by @AlexanderWilhelmsenBerg, originally posted 2026-09-15T15:21:58Z. Original comment

GitHub PR #161 merged successfully after full CI and focused device smoke, but its merge auto-closed this umbrella migration issue. Reopening #135 because BW-DEP-01 remains intentionally active across the remaining staged dependency/toolchain slices. The next active maintenance slice is GitHub PR #162 (Gradle 8.14.3 → 8.14.5); the Gradle 9 / AGP 9 / API 37 foundation remains gated by ADR-0011.

> Imported GitHub comment by **@AlexanderWilhelmsenBerg**, originally posted 2026-09-15T15:21:58Z. [Original comment](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/135#issuecomment-5682923626) [GitHub PR #161](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/161) merged successfully after full CI and focused device smoke, but its merge auto-closed this umbrella migration issue. Reopening #135 because BW-DEP-01 remains intentionally active across the remaining staged dependency/toolchain slices. The next active maintenance slice is [GitHub PR #162](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/162) (Gradle 8.14.3 → 8.14.5); the Gradle 9 / AGP 9 / API 37 foundation remains gated by ADR-0011.
Author
Owner

Imported GitHub comment by @AlexanderWilhelmsenBerg, originally posted 2026-09-15T17:48:08Z. Original comment

Reopened after GitHub PR #163 merged. #163 completed only the Room 2.7.2 → 2.8.5 Phase-4 slice; it did not complete BW-DEP-01. The issue acceptance criteria still require the remaining compatible runtime/network, visual, test, CI/tooling and dependency-automation work. Individual staged migration PRs must not close the umbrella issue.

> Imported GitHub comment by **@AlexanderWilhelmsenBerg**, originally posted 2026-09-15T17:48:08Z. [Original comment](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/135#issuecomment-5685189248) Reopened after [GitHub PR #163](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/163) merged. #163 completed only the Room 2.7.2 → 2.8.5 Phase-4 slice; it did not complete BW-DEP-01. The issue acceptance criteria still require the remaining compatible runtime/network, visual, test, CI/tooling and dependency-automation work. Individual staged migration PRs must not close the umbrella issue.
Author
Owner

Imported GitHub comment by @AlexanderWilhelmsenBerg, originally posted 2026-09-16T04:56:19Z. Original comment

Reopened after GitHub PR #167 auto-closed this umbrella migration issue. #167 completed only the first-party Retrofit kotlinx.serialization converter ownership/coordinates slice; Phase 5 still has the Retrofit and OkHttp major network-stack migrations outstanding, followed by later phases from the staged plan. Keep #135 open until the full migration program is complete.

> Imported GitHub comment by **@AlexanderWilhelmsenBerg**, originally posted 2026-09-16T04:56:19Z. [Original comment](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/135#issuecomment-5692254586) Reopened after [GitHub PR #167](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/167) auto-closed this umbrella migration issue. #167 completed only the first-party Retrofit kotlinx.serialization converter ownership/coordinates slice; Phase 5 still has the Retrofit and OkHttp major network-stack migrations outstanding, followed by later phases from the staged plan. Keep #135 open until the full migration program is complete.
Author
Owner

Imported GitHub comment by @AlexanderWilhelmsenBerg, originally posted 2026-09-16T07:18:42Z. Original comment

Post-#169 reconciliation is now in draft GitHub PR #170.

Phase 5 is reconciled as complete at the current mutually compatible stable frontier:

  • kotlinx.coroutines and Protobuf are at current stable;
  • Retrofit + the first-party serialization converter are at 3.0.0;
  • OkHttp is at 5.4.0, with 5.5.0 still API-37 / ADR-0011-gated;
  • kotlinx.serialization remains at the current Kotlin-2.2-compatible frontier, with 1.10+ compiler-gated;
  • javax.inject:1 has no version migration and needs no manufactured dependency PR;
  • the legacy MockWebServer compatibility artifact remains intentionally aligned; a mockwebserver3 package/API migration is not required for Phase-5 completion.

GitHub PR #170 also corrects stale Phase-4 status after merged Room #163. No runtime or dependency pins change. After this reconciliation merges, Phase 6 (Coil major, then Haze separately) is the next executable dependency lane.

Keep #135 open: Phases 6-9 plus the gated build/platform foundation remain outstanding.

> Imported GitHub comment by **@AlexanderWilhelmsenBerg**, originally posted 2026-09-16T07:18:42Z. [Original comment](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/135#issuecomment-5693569458) Post-#169 reconciliation is now in draft [GitHub PR #170](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/170). Phase 5 is reconciled as **complete at the current mutually compatible stable frontier**: - kotlinx.coroutines and Protobuf are at current stable; - Retrofit + the first-party serialization converter are at 3.0.0; - OkHttp is at 5.4.0, with 5.5.0 still API-37 / ADR-0011-gated; - kotlinx.serialization remains at the current Kotlin-2.2-compatible frontier, with 1.10+ compiler-gated; - `javax.inject:1` has no version migration and needs no manufactured dependency PR; - the legacy MockWebServer compatibility artifact remains intentionally aligned; a `mockwebserver3` package/API migration is not required for Phase-5 completion. [GitHub PR #170](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/170) also corrects stale Phase-4 status after merged Room #163. No runtime or dependency pins change. After this reconciliation merges, **Phase 6 (Coil major, then Haze separately)** is the next executable dependency lane. Keep #135 open: Phases 6-9 plus the gated build/platform foundation remain outstanding.
Sign in to join this conversation.
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
alexander/Audiobookshelf-Manager-Claude#42
No description provided.