Document Grails 7 plugin compatibility on Grails 8

[jamesfredley]

Summary

Expand the Grails 8 upgrade guide with symptom-driven guidance for using plugins built for Grails 7.

The new documentation:

• distinguishes application-side workarounds from failures that require a plugin rebuild
• documents the compatibility failures reproduced in Grails 7 plugins break at runtime after removal of Metadata dynamic and map-style key access #16122 through Grails 7 plugins shipping a Groovy 4-compiled @Immutable class fail on Grails 8 with NoClassDefFoundError: org/apache/groovy/runtime/ObjectUtil #16128
• adds before-and-after examples for Metadata, Jackson 2 dataformats, pre-Apache dependency coordinates, and Spring 7 HttpHeaders
• links the already-shipped legacy command, CLI companion, script packaging, and plugin bean lifecycle behavior from Register plugin beans before Spring Boot auto-configuration by retiming doWithSpring #15934, Split CLI dependencies from the runtime classpath #15948, Opt-in backwards compatibility for Grails 7 command plugins on Grails 8 #16011, and fix: route plugin src/main/scripts into companion -cli jars #16082
• corrects the existing guide's Holders.grailsApplication timing statement
• removes stale Spring Security and SiteMesh blocker guidance

Compatibility cases covered

• removed Metadata dynamic and map-style access
• Groovy 4 generic trait field-helper bytecode
• Groovy 4 AST transformations targeting private trait methods
• Groovy 4 @Immutable bytecode referencing removed ObjectUtil
• incomplete Jackson 2 Smile, CBOR, or YAML runtime classpaths
• versionless dependencies under pre-Apache org.grails coordinates
• Spring 6 HttpHeaders bytecode running against Spring Framework 7
• Grails 7 command plugins and retimed doWithSpring callbacks

Verification

• ./gradlew.bat :grails-doc:publishGuide -x :grails-doc:aggregateGroovydoc --max-workers=13
• Chromium QA of the generated guide/upgrading.html
  • all six new subsections rendered
  • code examples rendered
  • all seven issue links and four PR links were present
  • all four internal cross-references were clicked and reached visible targets
  • no browser console errors
• git diff --check
• mandatory Oracle review: GREEN
• mandatory Codex review: GREEN
• Checkstyle, CodeNarc, PMD, and SpotBugs aggregate reports: no violations
• aggregate unit tests: 12,316 passed, 0 failures

The mandatory aggregate integration run reached 3,617 tests and reported two unrelated failures:

• grails-test-examples-mail: a Windows-only CRLF assertion expected Hello\nWorld! but received Hello\r\nWorld!; it reproduced in an isolated serial rerun
• grails-test-examples-scaffolding: a browser test timed out on the welcome page during the full parallel run; the exact spec passed in an isolated serial rerun

Related issues

• Grails 7 plugins break at runtime after removal of Metadata dynamic and map-style key access #16122
• Grails 7 plugins exposing a generic trait with fields fail with MalformedParameterizedTypeException on Grails 8 #16123
• Incomplete Jackson 2 classpath breaks Grails 8 startup with NoClassDefFoundError in DefaultHttpMessageConverters #16124
• Plugins built against pre-Apache org.grails coordinates fail on Grails 8 with an empty-version resolution error #16125
• Grails 7 plugins whose AST transformation targets a private trait method silently lose it on Grails 8 #16126
• Grails 7 plugins passing HttpHeaders where a MultiValueMap is expected fail on Grails 8 with IncompatibleClassChangeError #16127
• Grails 7 plugins shipping a Groovy 4-compiled @Immutable class fail on Grails 8 with NoClassDefFoundError: org/apache/groovy/runtime/ObjectUtil #16128

[Copilot]

Pull request overview

Expands the Grails 8 upgrade guide with symptom-driven guidance for running Grails 7-built plugins on Grails 8, distinguishing application-side workarounds from failures that require a plugin rebuild.

Changes:

• Replaces the prior “known blockers” list with a symptom-based decision tree for common plugin/runtime failure modes.
• Adds detailed subsections covering Metadata access removal, Groovy 4→5 trait/AST bytecode breaks, Jackson 2 dataformat classpath pitfalls, pre-Apache org.grails coordinates, Spring 7 HttpHeaders binary incompatibility, and CLI/plugin lifecycle timing notes.
• Adds/repairs internal anchors and cross-references to make the new sections linkable and navigable.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 52.5524%. Comparing base (fa1e147) to head (9ef0225).

Additional details and impacted files

@@                Coverage Diff                 @@
##                8.0.x     #16141        +/-   ##
==================================================
+ Coverage     52.5503%   52.5524%   +0.0021%     
  Complexity      18391      18391                
==================================================
  Files            2037       2037                
  Lines           96498      96498                
  Branches        16860      16860                
==================================================
+ Hits            50710      50712         +2     
+ Misses          38353      38351         -2     
  Partials         7435       7435                

see 4 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[testlens-app]

✅ All tests passed ✅

🏷️ Commit: 9ef0225
▶️ Tests: 54503 executed
⚪️ Checks: 75/75 completed

---

Learn more about TestLens at testlens.app.

[sbglasius]

Should it be mentioned, that org.grails is often pre. Grails 7?

[jamesfredley]

@sbglasius I am going to skip this for now, since grails-plugin plugins still use org.grails for Grails 8+ plugins.

[jdaugherty]

We probably should create a plugin specific upgrade guide instead of adding to the already existing Grails 8 upgrade.