document simple enum converter

Author: codeconsole

grails-doc/src/en/guide/upgrading/upgrading60x.adoc

@@ -683,3 +683,74 @@ If your application or API consumers depend on the previous JSON format for `Cal
 4. **ZonedDateTime**: Note that the zone ID (e.g., `[America/Los_Angeles]`) is no longer included in the output, matching Spring Boot's behavior.
 
 This change applies to both the `grails-converters` module (standard JSON rendering) and the `grails-views-gson` module (JSON views).
+
+===== 12.26 Enum JSON/XML Serialization
+
+As of Grails 7.0.2, enum serialization has been enhanced to support round-trip compatibility between JSON/XML serialization and deserialization. The legacy enum marshaller, which produced verbose output with type metadata, has been deprecated in favor of a simpler format that matches how enums are expected on input.
+
+====== Legacy Behavior (Deprecated)
+
+Previously, enums were serialized with metadata:
+
+*JSON:*
+[source,json]
+----
+{
+  "stage": {
+    "enumType": "com.example.ChallengeStage",
+    "name": "SUBMIT"
+  }
+}
+----
+
+*XML:*
+[source,xml]
+----
+<stage enumType="com.example.ChallengeStage">SUBMIT</stage>
+----
+
+This format is **asymmetric** - when POSTing data, you send `"stage":"SUBMIT"`, but when GETting data, you receive the verbose object structure.
+
+====== New Behavior (Recommended)
+
+The new `SimpleEnumMarshaller` serializes enums as simple string values, providing **round-trip compatibility**:
+
+*JSON:*
+[source,json]
+----
+{
+  "stage": "SUBMIT"
+}
+----
+
+*XML:*
+[source,xml]
+----
+<stage>SUBMIT</stage>
+----
+
+Now the format you POST is the same format you GET back.
+
+====== Migration
+
+To opt-in to the new behavior, add the following to your `application.yml`:
+
+[source,yml]
+.application.yml
+----
+grails:
+  converters:
+    json:
+      enum:
+        format: simple
+    xml:
+      enum:
+        format: simple
+----
+
+====== Deprecation Timeline
+
+* **7.0.2**: Legacy `EnumMarshaller` deprecated (default), `SimpleEnumMarshaller` available via config
+* **8.0**: `SimpleEnumMarshaller` will become the default
+
+The legacy `org.grails.web.converters.marshaller.json.EnumMarshaller` and `org.grails.web.converters.marshaller.xml.EnumMarshaller` classes are marked as `@Deprecated(forRemoval = true, since = "7.0.2")` and will be removed in Grails 8.0.