This is an automated email from the ASF dual-hosted git repository. jamesfredley pushed a commit to branch docs/grails-8-api-compat-notes in repository https://gitbox.apache.org/repos/asf/grails-core.git
commit 16c17edee5ce997adff80318ccf1ea0fc9fefc5e Author: James Fredley <[email protected]> AuthorDate: Sat Jul 4 11:59:38 2026 -0400 Document Grails 8 API compatibility breaks Correct the enum marshaller migration note and add a Grails 8 extension API compatibility section for confirmed binary breaks. Assisted-by: Hephaestus:openai/gpt-5.5 --- .../src/en/guide/upgrading/upgrading80x.adoc | 77 +++++++++++++++++++++- 1 file changed, 76 insertions(+), 1 deletion(-) diff --git a/grails-doc/src/en/guide/upgrading/upgrading80x.adoc b/grails-doc/src/en/guide/upgrading/upgrading80x.adoc index c17cb0d63b..0aa8ae5c46 100644 --- a/grails-doc/src/en/guide/upgrading/upgrading80x.adoc +++ b/grails-doc/src/en/guide/upgrading/upgrading80x.adoc @@ -359,7 +359,9 @@ grails: format: simple ---- -If you need to restore the legacy behavior temporarily, the deprecated marshallers remain available but will be removed in a future release. +The legacy `org.grails.web.converters.marshaller.json.EnumMarshaller` and `org.grails.web.converters.marshaller.xml.EnumMarshaller` classes were removed in Grails 8. +There is no Grails 8 configuration switch that restores the verbose enum-object shape. +If an external API contract still requires that shape, register a custom object marshaller explicitly. ==== 9. Jackson 3 is the New Default @@ -1346,3 +1348,76 @@ grails: - Presto - Trident ---- + +==== 31. Extension API Compatibility Notes + +Most Grails applications do not call the Grails extension APIs listed below directly. +They can affect applications, plugins, or build logic that import these public classes or override these public extension points directly. +Unsupported internal implementation details are not covered here. + +[cols="1,2,2", options="header"] +|=== +| Module +| Changed or removed API +| Migration note + +| `grails-codecs` +| `org.grails.plugins.codecs.CodecsGrailsPlugin` no longer overrides `doWithSpring()` +| Do not depend on that plugin override to contribute codec bean definitions. +Custom plugins should register their own beans from their own `doWithSpring()` implementation. + +| `grails-controllers` +| `ControllersAutoConfiguration.dispatcherServletRegistration(...)` now returns Spring Boot 4's `org.springframework.boot.webmvc.autoconfigure.DispatcherServletRegistrationBean` +| Update direct imports, overrides, and binary integrations that referenced the Spring Boot 3 return type. + +| `grails-converters` +| `grails.web.JSONBuilder` +| Use Groovy's `groovy.json.JsonBuilder` or `groovy.json.StreamingJsonBuilder` for JSON builder code. + +| `grails-core` +| `GrailsApplicationPostProcessor` and `DefaultGrailsPluginManager` constructor signatures require `PluginDiscovery` +| Update custom bootstrapping code or subclasses to pass the plugin-discovery dependency. +This was introduced during the Grails 7.1 plugin-loading changes and remains required in Grails 8. + +| `grails-core` +| `grails.plugins.PluginFilter`, `IncludingPluginFilter`, `ExcludingPluginFilter`, `NoOpPluginFilter`, and related filter types +| Import the replacements from `org.apache.grails.core.plugins.filters.*`. + +| `grails-core` +| Legacy mixin transform APIs such as `grails.util.Mixin`, `MixinTargetAware`, and `MixinTransformation` +| Replace legacy mixin usage with Groovy traits, extension methods, or explicit composition. + +| `grails-core` +| `grails.validation.ConstraintsEvaluator` +| Use `org.grails.datastore.gorm.validation.constraints.eval.ConstraintsEvaluator`. + +| `grails-core` +| `BinaryGrailsPluginDescriptor`, `CorePluginFinder`, and `BinaryGrailsPlugin.getBinaryDescriptor()` +| Use the current plugin-discovery APIs and `BinaryGrailsPlugin.getPluginDescriptor()`. + +| `grails-domain-class` +| `ConstraintEvaluatorAdapter` and `GrailsDomainClassAutoConfiguration.constraintsEvaluator(...)` +| Code that imported the auto-configuration method should use the current `validateableConstraintsEvaluator(...)` bean path and the datastore constraint evaluator APIs. + +| `grails-fields` +| `BeanPropertyAccessor.getBeanClass()`, its setter, and `PropertyPathAccessor.getBeanClass()` +| Use the `beanType` property exposed by the accessors. +Custom field renderers should go through the documented tags and templates instead of calling private `render*` helpers directly. + +| `grails-gradle-plugins` +| `ApplicationContextCommandTask`, `ApplicationContextScriptTask`, `ProfileCompilerTask`, and `GrailsRunTask` are abstract; `GrailsGradlePlugin.createBuildPropertiesTask(...)` no longer returns a task value; several `IntegrationTestGradlePlugin` constants were removed +| Register these task types through Gradle task registration and update custom plugins that subclass `GrailsGradlePlugin` or read integration-test constants to use Gradle source sets, configurations, and the current test-phase APIs. + +| `grails-shell-cli` +| `AetherGrapeEngine` and `AetherGrapeEngineFactory` +| Use `MavenResolverGrapeEngine` and `MavenResolverGrapeEngineFactory` if you extend the legacy shell dependency resolver. + +| `grails-shell-cli` +| JLine 2 `complete(...)` signatures +| Implement the JLine 3 `org.jline.reader.Completer` contract, `complete(LineReader, ParsedLine, List<Candidate>)`. + +| `grails-spring` +| `GrailsApplicationContext.onRefresh()` +| Custom context subclasses should use supported Spring lifecycle extension points instead of overriding this removed hook. +Spring theme APIs removed from the same area are covered in section 10. +|===
