This is an automated email from the ASF dual-hosted git repository. jamesfredley pushed a commit to branch docs/grails-8-upgrade-guide-refresh in repository https://gitbox.apache.org/repos/asf/grails-core.git
commit c6cf03bb90ff23a3f1c9e5a36a029be3de096a4e Author: James Fredley <[email protected]> AuthorDate: Fri Jun 26 14:23:13 2026 -0400 Refresh Grails 8 platform upgrade docs Document the Spring Boot 4.1 baseline, Micronaut BOM guidance, and updated Grails 8 dependency references for users moving from Grails 7. Assisted-by: hephaestus:openai/gpt-5.5 oracle --- grails-doc/src/en/guide/conf/micronaut.adoc | 9 ++-- grails-doc/src/en/guide/introduction/whatsNew.adoc | 13 +++++- .../introduction/whatsNew/dependencyUpgrades.adoc | 2 + .../src/en/guide/upgrading/upgrading80x.adoc | 50 ++++++++++++++-------- 4 files changed, 52 insertions(+), 22 deletions(-) diff --git a/grails-doc/src/en/guide/conf/micronaut.adoc b/grails-doc/src/en/guide/conf/micronaut.adoc index 902d15a3e1..f7b1cf96e9 100644 --- a/grails-doc/src/en/guide/conf/micronaut.adoc +++ b/grails-doc/src/en/guide/conf/micronaut.adoc @@ -33,7 +33,7 @@ Here's an example build file: ---- dependencies { // enforcedPlatform is required: it forces grails-bom-managed versions over the - // versions declared by the Micronaut platform (e.g. javaparser-core, Groovy 4), + // versions declared by the Micronaut platform (for example Groovy 5 and javaparser-core), // preventing binary incompatibilities at runtime. implementation enforcedPlatform("org.apache.grails:grails-micronaut-bom:$grailsVersion") @@ -80,12 +80,13 @@ The Micronaut auto-setup defaults to on. If a project deliberately deviates from .build.gradle ---- grails { - micronautAutoSetup = false // not recommended — also skips the bootJar/bootWar CLASSIC loader configuration + micronautAutoSetup = false // not recommended - also skips Micronaut BOM validation } ---- -WARNING: Disabling auto-setup is rarely appropriate. Without `enforcedPlatform`, Gradle's default conflict resolution allows the Micronaut platform to silently override grails-bom-managed versions of libraries such as Groovy and `javaparser-core`, leading to binary incompatibilities at runtime. The CLASSIC loader configuration that auto-setup provides is also required for `java -jar` compatibility with the Micronaut-Spring integration. +WARNING: Disabling auto-setup is rarely appropriate. Without auto-setup, the Grails Gradle plugin will not validate that a Micronaut-compatible BOM is applied as `enforcedPlatform`. Without `enforcedPlatform`, Gradle's default conflict resolution allows the Micronaut platform to silently override grails-bom-managed versions of libraries such as Groovy and `javaparser-core`, leading to binary incompatibilities at runtime. ==== Generated Applications -Applications generated by https://forge.grails.org/[Grails Forge] with the Micronaut feature selected automatically use `enforcedPlatform("org.apache.grails:grails-micronaut-bom:$grailsVersion")` and require no further setup. \ No newline at end of file +Applications generated by https://forge.grails.org/[Grails Forge] with the Micronaut feature selected automatically use `enforcedPlatform("org.apache.grails:grails-micronaut-bom:$grailsVersion")` and require no further setup. +In Grails 8, Micronaut-enabled applications require JDK 25 or later; applications that do not use Micronaut continue to use the standard Java 21 baseline. diff --git a/grails-doc/src/en/guide/introduction/whatsNew.adoc b/grails-doc/src/en/guide/introduction/whatsNew.adoc index e40d79bff1..9c494096ab 100644 --- a/grails-doc/src/en/guide/introduction/whatsNew.adoc +++ b/grails-doc/src/en/guide/introduction/whatsNew.adoc @@ -27,6 +27,18 @@ This release focuses on enhancing the developer experience, improving performanc For detailed information on how to upgrade to Grails {grailsMajorVersion}, including major dependency changes, please see the xref:upgrading#upgrading80x[Upgrading from Grails 7 to Grails {grailsMajorVersion}] section. Notable new features are included below. +==== Platform Baseline + +Grails {grailsMajorVersion} raises the standard build and runtime baseline to Java 21 and uses Gradle {gradleVersion}. +The standard Grails BOM remains on Groovy {groovyVersion} and Spock {spockVersion}, while Micronaut-enabled Grails applications use Micronaut-specific BOM variants that align with Micronaut 5 and require JDK 25 or later. + +==== Spring Boot 4.1 and Spring Framework 7 + +Grails {grailsMajorVersion} is built on Spring Boot {springBootVersion} and Spring Framework {springVersion}. +This brings the Spring Boot 4 modular artifact layout, Spring Framework 7 API removals, Jackson 3, Tomcat 11 and Jakarta Servlet 6.1, plus Spring Boot 4.1 dependency management for Spring Security 7.1, Spring Data 2026.0 and Micrometer 1.17. + +The Grails 8 upgrade guide calls out the major application-impacting changes and links to the Spring Boot 4.0 migration guide, Spring Boot 4.1 release notes and Spring Framework 7.0 release notes. + ==== GSP Tag Library Improvements Grails {grailsMajorVersion} continues the move toward method-based TagLib handlers while preserving compatibility with existing closure-based tags. @@ -90,4 +102,3 @@ A single property can likewise declare a `$text` index — or another special ty When the options of an already-created index change between restarts, GORM now reconciles the difference instead of only logging a conflict. A changed TTL is applied in place with MongoDB's `collMod` command — no drop, no rebuild — while any other option change is applied by declaring `indexAttributes: [recreateOnConflict: true]`. - diff --git a/grails-doc/src/en/guide/introduction/whatsNew/dependencyUpgrades.adoc b/grails-doc/src/en/guide/introduction/whatsNew/dependencyUpgrades.adoc index f03c24d55d..9a8360f108 100644 --- a/grails-doc/src/en/guide/introduction/whatsNew/dependencyUpgrades.adoc +++ b/grails-doc/src/en/guide/introduction/whatsNew/dependencyUpgrades.adoc @@ -19,9 +19,11 @@ under the License. Grails {version} ships with the following foundational dependency versions: +* Java 21 minimum baseline * Groovy {groovyVersion} * Spring Framework {springVersion} * Spring Boot {springBootVersion} * Gradle {gradleVersion} * Spock {spockVersion} +See the link:{versionsRef}Grails%20BOM.html[Grails BOM dependency table] for the complete managed dependency set, including the Hibernate and Micronaut BOM variants. diff --git a/grails-doc/src/en/guide/upgrading/upgrading80x.adoc b/grails-doc/src/en/guide/upgrading/upgrading80x.adoc index 0d63da69b7..5eae1ae3fb 100644 --- a/grails-doc/src/en/guide/upgrading/upgrading80x.adoc +++ b/grails-doc/src/en/guide/upgrading/upgrading80x.adoc @@ -44,15 +44,18 @@ Grails 8 requires a minimum of Java 21 to both build and run Grails applications This is an increase from Grails 7, which required Java 17. Update your project's toolchain, CI pipelines, and deployment environments to use JDK 21 or later. -==== 2. Spring Boot 4.0.x +==== 2. Spring Boot 4.1.x -Grails 8 upgrades from Spring Boot 3.5.x to Spring Boot 4.0.x. -This is a major upgrade that brings Spring Framework 7.0.x, new module structure, and several breaking changes. +Grails 8 upgrades from Spring Boot 3.5.x to Spring Boot 4.1.x. +This crosses the Spring Boot 4 major release boundary and adopts the Spring Boot 4.1 managed stack used by Grails 8: Spring Framework 7.0.x, Spring Security 7.1.x, Spring Data 2026.0.x, Micrometer 1.17.x, Jackson 3.1.x, Tomcat 11.0.x, and Jakarta Servlet 6.1. +The upgrade includes the Spring Boot 4 module split, removed Spring Framework 6 deprecations, and additional Spring Boot 4.1 removals of APIs and properties that were deprecated in Spring Boot 4.0. For full details, consult: -1. https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes[Spring Boot 4.0 Release Notes] -2. https://github.com/spring-projects/spring-framework/wiki/Upgrading-to-Spring-Framework-7.x[Upgrading to Spring Framework 7] +1. https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide[Spring Boot 4.0 Migration Guide] +2. https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes[Spring Boot 4.0 Release Notes] +3. https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.1-Release-Notes[Spring Boot 4.1 Release Notes] +4. https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-7.0-Release-Notes[Spring Framework 7.0 Release Notes] ==== 3. Spring Boot Autoconfigure Modularization @@ -253,9 +256,10 @@ tasks.withType(BootArchive).configureEach { * The `grails-micronaut` plugin continues to work with Spring Boot 4's default loader. If you experience issues running your Micronaut-enabled Grails application via `java -jar`, please report them to the https://github.com/apache/grails-core/issues[Grails issue tracker]. -===== 7.2 enforcedPlatform Required for grails-bom +===== 7.2 enforcedPlatform Required for Micronaut BOMs -When using Micronaut, the `grails-bom` **must** be applied as `enforcedPlatform` instead of `platform`. +When using Micronaut, select a Micronaut-compatible Grails BOM and apply it as `enforcedPlatform` instead of `platform`. +The default choice is `grails-micronaut-bom`; Hibernate-specific variants are covered in section 7.4. The Micronaut 5 platform declares its own managed dependency versions that conflict with those managed by the `grails-bom`. Without `enforcedPlatform`, Gradle's default conflict resolution (highest version wins) allows the Micronaut platform to silently override `grails-bom` versions, leading to binary incompatibilities at runtime. @@ -265,22 +269,22 @@ For example, without `enforcedPlatform`: * **Spock** is upgraded from 2.3-groovy-4.0 to 2.4-groovy-5.0 -- compiled against Groovy 5, incompatible with Groovy 4 classes * **Kotlin**, **Mockito**, **Byte Buddy** are upgraded to versions not tested with the Grails stack -Using `enforcedPlatform` makes all `grails-bom` constraints strictly versioned so they cannot be overridden by any transitive dependency. +Using `enforcedPlatform` makes the selected Micronaut BOM constraints strictly versioned so they cannot be overridden by any transitive dependency. -The Grails Gradle Plugin will error at configuration time if `grails-micronaut` is detected and `grails-bom` is not applied as `enforcedPlatform`. +The Grails Gradle Plugin will error at configuration time if `grails-micronaut` is detected and no Micronaut-compatible Grails BOM is applied as `enforcedPlatform`. [source,groovy] .build.gradle ---- dependencies { // enforcedPlatform is required when using grails-micronaut - implementation enforcedPlatform("org.apache.grails:grails-bom:$grailsVersion") + implementation enforcedPlatform("org.apache.grails:grails-micronaut-bom:$grailsVersion") implementation 'org.apache.grails:grails-micronaut' } ---- -NOTE: Applications generated by the Grails Forge automatically use `enforcedPlatform` when the Micronaut feature is selected. +NOTE: Applications generated by the Grails Forge automatically use the appropriate Micronaut BOM as `enforcedPlatform` when the Micronaut feature is selected. ===== 7.3 Micronaut Features Require JDK 25 @@ -360,7 +364,7 @@ If you need to restore the legacy behavior temporarily, the deprecated marshalle ==== 9. Jackson 3 is the New Default Spring Boot 4 ships Jackson 3 (`tools.jackson.*`) and auto-configures a `JsonMapper` bean instead of the Jackson 2 `ObjectMapper`. -Grails 8 follows that change: any Grails module that previously declared `com.fasterxml.jackson.core:jackson-databind` (Jackson 2) now declares `tools.jackson.core:jackson-databind` (Jackson 3, currently 3.1.0 via the Spring Boot 4 BOM). +Grails 8 follows that change: any Grails module that previously declared `com.fasterxml.jackson.core:jackson-databind` (Jackson 2) now declares `tools.jackson.core:jackson-databind` (Jackson 3.1.x via the Spring Boot 4.1 BOM). **What stayed the same:** @@ -400,7 +404,7 @@ Spring Boot 4 provides a `tools.jackson.databind.json.JsonMapper` bean instead o Update injection points to expect `JsonMapper`. **If you must stay on Jackson 2 temporarily:** -Spring Boot 4 still manages the Jackson 2 BOM (currently 2.21.2) and provides an opt-in toggle so the auto-configured mapper preserves Jackson 2 defaults: +Spring Boot 4 still manages the Jackson 2 BOM and provides an opt-in toggle so the auto-configured mapper preserves Jackson 2 defaults: [source,yaml] .application.yml @@ -764,12 +768,24 @@ If your application *directly* uses `@Retryable`, `@EnableRetry`, or `@Recover`, implementation 'org.springframework.retry:spring-retry' ---- -NOTE: The `grails-bom` pins a known-good Spring Retry version (`2.0.x`), so you do not need to specify a version when using `enforcedPlatform("org.apache.grails:grails-bom:$grailsVersion")`. +NOTE: The `grails-bom` pins a known-good Spring Retry version (`2.0.x`), so you do not need to specify a version when your build uses the Grails BOM, whether it is auto-applied by the Grails Gradle plugin or declared explicitly. Override the BOM-managed version in your build if you need a newer release. ==== 20. Other Default Behavior Changes -Spring Boot 4 made several smaller default-behavior changes that you may notice but rarely require code changes: +Spring Boot 4.0 and 4.1 made several smaller default-behavior changes that you may notice but rarely require code changes: + +* **Spring Boot 4.1 removes Spring Boot 4.0 deprecations.** +If you tested against an earlier Grails 8 snapshot or Spring Boot 4.0.x directly, remove any use of APIs, methods, or configuration properties that were only deprecated there before moving to the current Grails 8 line. + +* **The Spring Boot `BuildInfo` task writes `META-INF/build-info.properties` by default.** +If your build, packaging, or tests read `build-info.properties` from the root of the generated resources directory, update them to read `META-INF/build-info.properties` or configure the task's `filename` property. + +* **Spring Data JPA repository bootstrap modes were tightened.** +Grails GORM is unaffected, but applications that also use Spring Data JPA directly should review any `spring.data.jpa.repositories.bootstrap-mode` setting when moving to Spring Boot 4.1. + +* **Derby support is deprecated in Spring Boot.** +Grails does not use Derby by default, but applications that added Derby through Spring Boot auto-configuration should plan a migration to H2, HSQLDB, or another supported database. * **Logback default charset is now `UTF-8`** for log files (aligning with the existing Log4j2 default). Console output uses `Console#charset()` if available, otherwise `UTF-8`. @@ -1227,7 +1243,7 @@ grails.gorm.default.constraints = { } ---- -==== 27. MIME Types Are Now Framework Defaults +==== 28. MIME Types Are Now Framework Defaults Grails 8 ships the full set of supported MIME types as built-in framework defaults. Previously every newly generated application declared a `grails.mime.types` block in `grails-app/conf/application.yml`; the Grails Forge and the application profiles no longer generate that block, because the framework now supplies the same defaults out of the box. @@ -1250,7 +1266,7 @@ grails: custom: application/vnd.example+json ---- -==== 28. Accept Header Honored for All Clients +==== 29. Accept Header Honored for All Clients Grails 8 honors the HTTP `Accept` header for content negotiation for **every** client by default, including browsers.
