Add spec for Configuration Cache support (#164)#184
Merged
Conversation
Defensive verify-and-prove approach: plugin already structurally CC-compatible per architecture-expert review; spec captures verification methodology, audit artifacts, and documentation work for v1.0.0-Beta. Floor: Gradle 9+ / AGP 9+. Reviewed via multiexpert-review (2 cycles, business-analyst + architecture-expert) before approval. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Review Summary by QodoAdd spec for Configuration Cache support in featured-gradle-plugin
WalkthroughsDescription• Adds comprehensive spec for Configuration Cache support in featured-gradle-plugin • Defines 9 acceptance criteria covering automated test parametrization, manual verification, and documentation • Establishes defensive verify-and-prove approach with directory-snapshot cache assertions • Includes AGP propagation verification methodology and isolated-projects deferral to v1.1.0 • Specifies audit artifacts and technical constraints for Gradle 9+ / AGP 9+ floor Diagramflowchart LR
A["Spec Definition"] --> B["9 Acceptance Criteria"]
B --> C["Test Parametrization<br/>AC-1, AC-2"]
B --> D["Manual Verification<br/>AC-3, AC-4"]
B --> E["AGP Propagation Check<br/>AC-5a, AC-5b"]
B --> F["Documentation<br/>AC-6, AC-7, AC-8"]
C --> G["Directory-Snapshot<br/>Cache Assertion"]
D --> H["Audit Artifacts<br/>Markdown Reports"]
E --> I["Provider Exposure<br/>R8 Input Verification"]
F --> J["README, CHANGELOG,<br/>known-limitations.md"]
File Changes1. docs/specs/2026-05-16-gradle-plugin-cc-support.md
|
There was a problem hiding this comment.
Pull request overview
Adds an approved specification for Configuration Cache support verification and documentation in featured-gradle-plugin, covering automated TestKit checks, manual audit artifacts, AGP ProGuard/R8 propagation validation, and release documentation requirements.
Changes:
- Defines acceptance criteria for Configuration Cache test parametrization and cache reuse proof.
- Specifies manual verification artifacts for fixture, samples, and AGP propagation.
- Documents scope, constraints, decisions, and future isolated-projects work.
Comments suppressed due to low confidence (1)
docs/specs/2026-05-16-gradle-plugin-cc-support.md:49
- AC-3 requires locating and inspecting
configuration-cache-report.htmlafter a successful--configuration-cache-problems=failrun, but Gradle may not emit a configuration-cache HTML problem report when there are zero problems. That makes the “zero violations” proof depend on a file that can legitimately be absent on the passing path; the criterion should treat a successful fail-on-problems build as the zero-violation signal or specify a warn-mode report collection step when a report is expected.
- [ ] **AC-3** — Manual run of `./gradlew assembleRelease --configuration-cache --configuration-cache-problems=fail` against the test fixture under `featured-gradle-plugin/src/test/fixtures/android-project/` completes successfully. The configuration-cache HTML report (located via `find build/reports/configuration-cache -name configuration-cache-report.html`) contains zero violations attributable to `featured-gradle-plugin` source. **Audit artifact** committed at `docs/cc-verification/fixture-report-2026-05-16.md` (Markdown summary only — raw HTML reports MUST NOT be committed) with the following content schema, all sections present:
- Gradle version used (output of `./gradlew --version`)
- AGP version used (from fixture `build.gradle.kts`)
- Exact command invoked
- Total violation count
- Per-violation table with columns: `source plugin | violation category | upstream issue link (if any)` (empty table acceptable if zero violations)
- Conclusion paragraph (one sentence stating whether AC-3 passes and why)
Comment on lines
+30
to
+43
| **Success metric (outcome).** A consumer enables Configuration Cache (`org.gradle.configuration-cache=true` in `gradle.properties`), applies `featured-gradle-plugin` to their module, and observes (a) zero Configuration Cache report entries attributed to `featured-gradle-plugin` source, and (b) the second build in the same project directory reuses the cache (LOAD, no new hash directory created under `build/reports/configuration-cache/`). The test fixture under `featured-gradle-plugin/src/test/fixtures/android-project/` serves as the canonical consumer surrogate — verification on it is the proxy for verification across consumer projects. AC-1 through AC-8 are the proof artifacts of this outcome; they exist to make the success metric automatically verifiable in CI. | ||
|
|
||
| ## Acceptance Criteria | ||
|
|
||
| The feature is complete when ALL of the following are true. | ||
|
|
||
| - [ ] **AC-1** — `FeaturedPluginIntegrationTest` is parametrized over `cc: Boolean`. When `cc=true`, `GradleRunner` invocations include `--configuration-cache --configuration-cache-problems=fail`, and the test runs the build twice in the same project directory. Cache state is asserted via **directory-snapshot of `build/reports/configuration-cache/`**: | ||
| - Before run 1: snapshot the set of top-level subdirectories (`hashSetBefore`). | ||
| - Run 1 (must STORE): assert exactly one new top-level subdirectory appears (`hashSetAfter1 - hashSetBefore == { exactly one new entry }`). This entry is the freshly-stored CC state. | ||
| - Run 2 (must LOAD): assert no new top-level subdirectory appears (`hashSetAfter2 == hashSetAfter1`). Identical-set means Gradle reused the existing CC entry rather than creating a new one. | ||
| - Tests MUST also fail if `build/reports/configuration-cache/` is absent after either run — that indicates CC was not actually enabled by the build at all. | ||
| - Free-text grep of TestKit output (e.g. `"Reusing configuration cache."`) and Configuration Cache HTML report parsing are both explicitly NOT acceptable — the log strings and report internals are not part of Gradle's public API and change across minors. Directory existence and set comparison are observable filesystem state. | ||
| - [ ] **AC-2** — Both parametrized scenarios (`cc=false`, `cc=true`) pass in the CI test job. No new CI job is required. | ||
| - [ ] **AC-3** — Manual run of `./gradlew assembleRelease --configuration-cache --configuration-cache-problems=fail` against the test fixture under `featured-gradle-plugin/src/test/fixtures/android-project/` completes successfully. The configuration-cache HTML report (located via `find build/reports/configuration-cache -name configuration-cache-report.html`) contains zero violations attributable to `featured-gradle-plugin` source. **Audit artifact** committed at `docs/cc-verification/fixture-report-2026-05-16.md` (Markdown summary only — raw HTML reports MUST NOT be committed) with the following content schema, all sections present: |
Comment on lines
+43
to
+44
| - [ ] **AC-3** — Manual run of `./gradlew assembleRelease --configuration-cache --configuration-cache-problems=fail` against the test fixture under `featured-gradle-plugin/src/test/fixtures/android-project/` completes successfully. The configuration-cache HTML report (located via `find build/reports/configuration-cache -name configuration-cache-report.html`) contains zero violations attributable to `featured-gradle-plugin` source. **Audit artifact** committed at `docs/cc-verification/fixture-report-2026-05-16.md` (Markdown summary only — raw HTML reports MUST NOT be committed) with the following content schema, all sections present: | ||
| - Gradle version used (output of `./gradlew --version`) |
Comment on lines
+164
to
+166
| 3. **Experiment.** Locally remove `AndroidProguardWiring.kt:30-34` (or comment out). Inject a marker into the generated ProGuard rules — extend `ProguardRulesGenerator` to append a comment `# featured-cc-marker: ${UUID}` (UUID generated per run, captured in test) to the output. Run the fixture E2E with `--configuration-cache --info`. Assert **both**: | ||
| - `:generateProguardRules` appears in the executed task graph BEFORE the R8 task (parse `--info` log or use TestKit `BuildResult.tasks` ordering). | ||
| - The marker UUID appears in R8's merged input — search candidate locations: `build/intermediates/proguard_files/release/*`, `build/intermediates/r8_d8_compat_proguard/release/*`, or grep `--info` log lines that name files R8 read. The implementing agent identifies the actual location during the experiment and records it in the audit artifact. |
Comment on lines
+172
to
+177
| - CHANGELOG: single line under `[1.0.0-Beta]` → `### Added` → `- Configuration Cache support (Gradle 9+, AGP 9+)`. Format consistent with existing entries. | ||
| - `docs/known-limitations.md`: structured by topic — Configuration Cache, isolated projects, third-party plugin gaps. Each entry: short statement + link to upstream issue + target Featured version for resolution. The isolated-projects entry MUST link to a GitHub issue passing the `gh issue view` external proof in AC-8 (use `gh issue create --milestone v1.1.0 --title "isolated projects: migrate wireToRootAggregator away from rootProject access"`). | ||
|
|
||
| ## Technical Constraints | ||
|
|
||
| - Plugin supports Gradle 9+ and AGP 9+ for v1.0.0-Beta. Wider compatibility is NOT promised and may be evaluated for v1.0.0 stable based on Beta feedback. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
featured-gradle-pluginReview
Spec was reviewed via
/multiexpert-review(2 cycles, business-analyst + architecture-expert) before approval. Cycle 1 surfaced 4 major + 7 minor items (all applied). Cycle 2 surfaced 1 critical (escalated by cross-agent consensus) + 2 majors around cache-reuse assertion strategy and AGP propagation methodology — all applied via directory-snapshot mechanism and R8 input verification.Scope
Spec only — implementation lands in a separate PR per #164.
Test plan
🤖 Generated with Claude Code