From a317f8a4a5bc8166aec9252af88dd43a7983d732 Mon Sep 17 00:00:00 2001 From: Claw Date: Sun, 19 Jul 2026 04:10:20 -0700 Subject: [PATCH] =?UTF-8?q?F-018:=20close=20ticket=20=E2=80=94=20align=20d?= =?UTF-8?q?ocs=20to=208.x=20terminal=20baseline?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Product ladder already on v2 via #179–#182. Living docs still claimed AGP 8.1.2 / Gradle 8.7 / Kotlin 1.9.22 as current; refresh ENV, ARCHITECTURE, COMPOSE, GETTING-STARTED, mark F-018 done. --- TICKETS.md | 2 +- docs/ARCHITECTURE.md | 34 ++++++++++++++++++---------------- docs/COMPOSE.md | 7 +++++-- docs/ENV.md | 12 +++++++----- docs/GETTING-STARTED.md | 13 +++++++------ docs/PROGRESS.md | 21 +++++++++++++++++++++ 6 files changed, 59 insertions(+), 30 deletions(-) diff --git a/TICKETS.md b/TICKETS.md index 85813b2..9694b48 100644 --- a/TICKETS.md +++ b/TICKETS.md @@ -12,7 +12,7 @@ Update this file when picking or finishing work. Cron workers must pick the **hi | F-002 | done | Audit build graph: plugins, sample app, CI workflows | Map modules → forma-core candidates; capture in `docs/ARCHITECTURE.md` | | F-003 | done | Get plugins + sample `application/` building on modern toolchain | Plugins compile AGP 8.1.2 matches sample; Gradle 8.3 (plugins) / 8.4 (app); host builds green | | F-004 | done | CI green on GitHub Actions for plugins + application | Temurin 17 all jobs + Android SDK 33 for app; PR #153 GHA green | -| F-018 | in_progress | JDK 21 + Gradle/AGP staged modernization | **2026-07-19 deps PR:** Gradle **8.14.5**, AGP **8.13.2**, Kotlin **2.0.21**, KSP **2.0.21-1.0.28**, Compose **1.9.4**/compiler **2.0.21**, sample libs modernized (AGP-8.13/SDK-35 ceiling). JDK 21 host/CI already. AGP 9 = F-019. | +| F-018 | done | JDK 21 + Gradle/AGP staged modernization | **Shipped on `v2`:** Gradle **8.14.5**, AGP **8.13.2**, Kotlin **2.0.21**, KSP **2.0.21-1.0.28**, Compose **1.9.4**/compiler **2.0.21**, JDK **21** host/CI, sample SDK min23/target35/compile35 + deps at AGP-8.13 ceiling. PRs **#179–#182**. AGP 9 / absolute-latest AndroidX = **F-019** (explicit OK only). | ## P1 — Android working product diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 48cca26..6e2806a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -4,7 +4,7 @@ Living map of the monorepo build graph, plugin modules, sample app, CI, and what should become **forma-core**. Source of truth for F-002; update when the graph changes. -Last audited: **2026-07-11** (worker host green after F-001). +Last audited: **2026-07-19** (F-018 8.x terminal toolchain on `v2`). --- @@ -16,11 +16,11 @@ that compose via `includeBuild`: | Path | Role | Gradle wrapper | Publishes / consumed as | |------|------|----------------|-------------------------| -| `plugins/` | Forma Gradle plugins (main product) | 8.7 | Composite + Plugin Portal (`tools.forma.*`) | -| `application/` | Sample Android product (gold standard) | 8.7 | Consumer only | -| `jvm-application/` | Sample pure-JVM product (`tools.forma.jvm`) | 8.7 | Consumer only | -| `includer/` | Settings plugin: auto-`include` subprojects | (own wrapper) | `tools.forma.includer` | -| `depgen/` | Transitive-deps generation plugin | (own wrapper) | `tools.forma.depgen` (standalone) | +| `plugins/` | Forma Gradle plugins (main product) | 8.14.5 | Composite + Plugin Portal (`tools.forma.*`) | +| `application/` | Sample Android product (gold standard) | 8.14.5 | Consumer only | +| `jvm-application/` | Sample pure-JVM product (`tools.forma.jvm`) | 8.14.5 | Consumer only | +| `includer/` | Settings plugin: auto-`include` subprojects | 8.14.5 | `tools.forma.includer` | +| `depgen/` | Transitive-deps generation plugin | 8.14.5 | `tools.forma.depgen` (standalone) | | `build-settings/` | Shared settings conventions (repos) | — | `includeBuild` / convention plugins | | `build-dependencies/` | Typed external dep catalogs for sample | — | `includeBuild` as `tools.forma.demo:dependencies` | | `docs/`, `scripts/` | Worker/env docs (not Gradle) | — | — | @@ -55,7 +55,7 @@ that compose via `includeBuild`: - `includeBuild("../build-settings")`, `../plugins`, `../includer` - Settings plugins: `convention-dependencies`, `tools.forma.includer`, `tools.forma.android`, Gradle Enterprise - `includeBuild("../build-dependencies")` for demo catalog -- Heavy `buildscript` resolution forces (AGP 8.1.2, bundletool, asm, guava, …) +- Heavy `buildscript` resolution forces (AGP **8.13.2**, bundletool, asm, guava, …) **Plugins build** (`plugins/settings.gradle.kts`): @@ -110,9 +110,10 @@ Group/version (root `plugins/build.gradle.kts`): **`tools.forma` / `0.1.3`**. | `:android` | `tools.forma.android` | `:core` + all of the above + **AGP** + Kotlin GP | Target DSL; `AndroidTargetTypes` + `AndroidRestrictionKit` (F-021); content helpers call core `ContentRule` (F-022) | | `:jvm` | `tools.forma.jvm` | `:core`, `:deps`, `:validation`, `:target`, `:owners` + Kotlin GP (**no AGP**) | Pure JVM DSL (`api`/`impl`/`library`/`util`/`testUtil` in package `tools.forma.jvm`); `JvmTargetTypes` + `JvmTargetRegistry` (F-030) | -`:android` compiles against **AGP 8.1.2** (aligned with sample runtime force in -`application/settings.gradle.kts` as of F-003). Keep `plugins/android` AGP -compile dep and consumer `agpVersion` in lockstep. +`:android` compiles against **AGP 8.13.2** (aligned with sample +`androidProjectConfiguration(agpVersion = …)` — F-018 / #182). Keep +`plugins/android` AGP compile dep and consumer `agpVersion` in lockstep. +AGP 9 is **F-019** only with explicit OK. `publishPlugins` on `:android` depends on publishing all sibling plugins. @@ -280,8 +281,8 @@ Concurrency group `ci-${{ github.workflow }}-${{ github.ref }}` cancels in-progr CI pins (evolved F-004 → F-018): -1. **All jobs** pin Temurin **21** via `actions/setup-java@v4` (was 17; requires Gradle ≥8.5 — wrappers are **8.7**). -2. **Application** installs Android SDK packages matching sample `compileSdk` 34 / target 33. +1. **All jobs** pin Temurin **21** via `actions/setup-java@v4` (was 17; requires Gradle ≥8.5 — wrappers are **8.14.5**). +2. **Application** installs Android SDK packages matching sample `compileSdk` **35** / target **35**. 3. README badge → `formatools/forma` + `actions/workflows/main.yml/badge.svg`. 4. Gradle setup via `gradle/actions/setup-gradle@v4` (successor of `gradle-build-action`). 5. Dropped unconditional `--scan` (no build-scan account coupling in CI). @@ -297,10 +298,10 @@ keys) or full Portal publish via secrets; deeper Gradle remote cache. |-----------|---------------------| | JDK (daemon / CI) | **21** (CI Temurin 21; host OpenJDK 21 via Homebrew `openjdk@21`) | | App bytecode / `jvmTarget` | unchanged (sample default `JavaVersion.VERSION_1_8`) — not raised with daemon JDK | -| Gradle | **8.14.5** (all wrappers; F-018 deps bump / PR #180) | -| AGP | **8.1.2** sample runtime + plugins compile (aligned F-003; AGP ladder = later F-018) | -| Kotlin | embeddedKotlin from Gradle 8.7 (**1.9.22**); Compose compiler default **1.5.10** | -| Android SDK | sample compileSdk **35** / target 33; host platforms 34+33 + build-tools 33/34 | +| Gradle | **8.14.5** (all wrappers; F-018 #180→#182) | +| AGP | **8.13.2** sample runtime + plugins compile (F-018 / #182) | +| Kotlin | embeddedKotlin from Gradle 8.14.5 (**2.0.21**); KSP **2.0.21-1.0.28**; Compose compiler default **2.0.21** | +| Android SDK | sample min **23** / target **35** / compile **35**; host platforms 35+34+33 + build-tools 33/34 | | Forma version | 0.1.3 | Host bootstrap details: `docs/ENV.md`, `scripts/env-mac.sh` (F-001). @@ -352,6 +353,7 @@ Suggested extraction order (tickets F-020…F-024): | ~~README dependency matrix ≠ live validators~~ → [`docs/DEPENDENCY-MATRIX.md`](DEPENDENCY-MATRIX.md) | F-010 done | | ~~`EmptyValidator` on app/binary/(historical androidLibrary)~~ (composition-root + library allowlists) | F-011 done; androidLibrary removed F-063 | | ~~AGP 7.4.2 compile vs 8.1.2 runtime~~ (aligned 8.1.2) | F-003 done | +| ~~F-018 8.x ladder~~ (JDK 21, Gradle 8.14.5, AGP 8.13.2, deps) | F-018 done (#179–#182); AGP 9 = F-019 | | ~~CI missing SDK + Java on some jobs~~ (GHA green on PR #153) | F-004 done | | ~~Compose flag in settings, limited target support~~ → per-target flags + `composeWidget` | F-013 done | | ~~Missing Android getting-started tutorial~~ → [`docs/GETTING-STARTED.md`](GETTING-STARTED.md) | F-015 done | diff --git a/docs/COMPOSE.md b/docs/COMPOSE.md index 79825e1..d1a3174 100644 --- a/docs/COMPOSE.md +++ b/docs/COMPOSE.md @@ -97,8 +97,11 @@ Full matrix: [`DEPENDENCY-MATRIX.md`](DEPENDENCY-MATRIX.md). ## Compiler / Kotlin pairing -Default `composeCompilerVersion = "2.0.21"` matches Kotlin **1.9.22** (Gradle 8.7 -embedded Kotlin used by the sample). If you bump Kotlin, update +Default `composeCompilerVersion = "2.0.21"` matches Kotlin **2.0.21** (Gradle +**8.14.5** embedded Kotlin used by the sample). On Kotlin **2.0+**, Forma also +applies the **Compose Compiler Gradle plugin** when `compose = true` (the +`composeCompilerVersion` value remains the paired compiler coordinate for AGP +`composeOptions` / tooling). If you bump Kotlin, update `composeCompilerVersion` using the [Compose Compiler compatibility map](https://developer.android.com/jetpack/androidx/releases/compose-kotlin). diff --git a/docs/ENV.md b/docs/ENV.md index 285d7f6..66e0261 100644 --- a/docs/ENV.md +++ b/docs/ENV.md @@ -76,14 +76,16 @@ sudo ln -sfn /usr/local/opt/openjdk@21/libexec/openjdk.jdk \ /Library/Java/JavaVirtualMachines/openjdk-21.jdk ``` -## Verified on 2026-07-19 (F-018 Phase 1 + JDK 21) +## Verified on 2026-07-19 (F-018 complete — 8.x terminal) - `java` / `javac` **21.x** (Homebrew OpenJDK 21) via `scripts/env-mac.sh` -- Gradle wrappers: **8.7** (all roots; was 8.3/8.4 split — PR #180) -- Compose compiler default **2.0.21** (Kotlin **2.0.21** / Gradle 8.14.5 embedded) -- AGP still **8.1.2** (Phase 2+ climb is later F-018 work) +- Gradle wrappers: **8.14.5** (all roots; unified via #180 then #182) +- AGP **8.13.2** lockstep (`plugins/android` compile + sample `agpVersion`) +- Kotlin **2.0.21** (Gradle embedded); KSP **2.0.21-1.0.28** +- Compose compiler default **2.0.21** (+ Kotlin Compose Compiler plugin when `compose=true`) +- Sample SDK: min **23** / target **35** / compile **35** (install platform 35 for full sample builds; 34/33 still useful) - CI: Temurin **21** all jobs (`.github/workflows/main.yml`) -- Toolchain note: plugins compile AGP matches sample forced AGP (no 7.4.2 skew) +- AGP 9 / Gradle 9 / absolute-latest AndroidX = **F-019** only with explicit OK See `docs/PROGRESS.md` for the latest host build tails. diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md index 853a99d..5d674dd 100644 --- a/docs/GETTING-STARTED.md +++ b/docs/GETTING-STARTED.md @@ -40,9 +40,10 @@ structure and boundaries, not business logic. | Tool | Version / notes | |------|-----------------| | JDK | **21** build/daemon (F-018); app language level unchanged | -| Android SDK | Platform **34** (`compileSdk`; required for modern Compose AARs), **33** useful for `targetSdk` | +| Android SDK | Platform **35** (`compileSdk` / modern Compose + AndroidX AARs); **34**/**33** still useful | | Build tools | 33.0.2 / 34.0.0 as used by the sample | -| Gradle | Use the wrapper in the project (`./gradlew`); **8.7** all roots | +| Gradle | Use the wrapper in the project (`./gradlew`); **8.14.5** all roots | +| AGP | **8.13.2** (keep consumer `agpVersion` aligned with plugin compile AGP) | Worker / macOS install steps: [ENV.md](ENV.md) (`source scripts/env-mac.sh`). @@ -408,13 +409,13 @@ Details: [COMPOSE.md](COMPOSE.md). Sample: | Symptom | Likely cause | |---------|----------------| -| “Java not found” / old JDK | Use JDK 17+; export `JAVA_HOME` ([ENV.md](ENV.md)) | -| SDK / `compileSdk` errors | Install platform 34; set `local.properties` `sdk.dir` | +| “Java not found” / old JDK | Use JDK 21 (or 17+ min); export `JAVA_HOME` ([ENV.md](ENV.md)) | +| SDK / `compileSdk` errors | Install platform **35**; set `local.properties` `sdk.dir` | | Project not included | Missing `build.gradle.kts`, or nested `settings.gradle.kts` blocked Includer | | Illegal project dependency | Matrix violation — see [DEPENDENCY-MATRIX.md](DEPENDENCY-MATRIX.md) | | Empty / wrong package | `packageName` ≠ directory under `src/main/java` | | Compose compiler mismatch | Align `composeCompilerVersion` with Kotlin (sample: 2.0.21 ↔ 2.0.21) | -| AGP resolution conflicts | Align consumer `agpVersion` with plugin AGP line (**8.1.2** today) | +| AGP resolution conflicts | Align consumer `agpVersion` with plugin AGP line (**8.13.2** today) | --- @@ -442,4 +443,4 @@ Details: [COMPOSE.md](COMPOSE.md). Sample: - [ ] No `impl` → `impl` edges - [ ] Composition roots list feature entrypoints explicitly - [ ] External versions live in a catalog, not copy-pasted GAVs in every target -- [ ] `./gradlew :binary:assembleDebug` succeeds on a clean machine with JDK 17 + SDK 34 +- [ ] `./gradlew :binary:assembleDebug` succeeds on a clean machine with JDK 21 + SDK 35 diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index 5596b86..80414d9 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -2,6 +2,27 @@ Newest entries first. +## 2026-07-19 — F-018 close: docs soak + ticket done + +- **Ticket:** F-018 → `done` (8.x terminal toolchain; AGP 9 = F-019 only with explicit OK) +- **Branch / PR:** `forma/F-018-docs-close` → base `v2` +- **Skills/modes:** Hermes orchestrator only (mechanical F-018 docs/CI pin class — no Grok Build product coding) +- **Why this slice:** Product ladder already on tip via #179–#182; tip CI [29680345620](https://github.com/formatools/forma/actions/runs/29680345620) **SUCCESS**. Several living docs still claimed AGP **8.1.2** / Gradle **8.7** / Kotlin **1.9.22** as current. +- **Docs aligned to live baseline:** + - `docs/ENV.md` — verified section → Gradle **8.14.5**, AGP **8.13.2**, Kotlin/KSP **2.0.21**, Compose **2.0.21**, sample SDK 23/35/35 + - `docs/ARCHITECTURE.md` — wrapper table, AGP compile line, CI SDK pins, toolchain snapshot, F-018 done row + - `docs/COMPOSE.md` — compiler pairing Kotlin **2.0.21** + Compose Compiler plugin note + - `docs/GETTING-STARTED.md` — tools table, pitfalls, checklist (JDK 21 + SDK 35) + - `TICKETS.md` — F-018 `done` with #179–#182 summary +- **Product code:** none (versions already correct on `v2` @ `47c2e70`) +- **Verify (real host, `source scripts/env-mac.sh`):** + - `java -version` → **21.0.11** + - `plugins/ ./gradlew --version` → **Gradle 8.14.5** / Kotlin **2.0.21** / JVM 21 + - `plugins/ ./gradlew build` → **BUILD SUCCESSFUL** (78 tasks) + - `application/ ./gradlew build` → **BUILD SUCCESSFUL** (2554 tasks) +- **Blockers:** none +- **Next:** prioritized queue empty unless user adds F-xxx or promotes backlog (#110, #97, #88, #82, Portal #133) or explicitly OKs **F-019** AGP 9 + ## 2026-07-19 — F-018 deps: Gradle 8.14.5 + AGP 8.13.2 + library refresh - **Ticket:** F-018 remains `in_progress` (8.x terminal toolchain + sample deps; AGP 9 = F-019)