stevenschlansker commented on code in PR #3714:
URL: https://github.com/apache/fory/pull/3714#discussion_r3352762501
##########
docs/guide/java/row-format.md:
##########
@@ -113,6 +113,78 @@ Row format is ideal for:
- **Data pipelines**: Processing data without full object reconstruction
- **Cross-language data sharing**: When data needs to be accessed from
multiple languages
+## Schema evolution
+
+Enable `.withSchemaEvolution()` on a row, array, or map codec builder to read
payloads written
+by older versions of the same bean. Writing always uses the current version;
reading detects
+the payload's version from a strict hash at the head of the payload. Java only.
+
+Annotate fields added after v1 with `@ForyVersion(since = N)`:
+
+```java
+@Data
+public class Person {
+ private String name;
+ private int age;
+
+ @ForyVersion(since = 2)
+ private String email;
+}
+```
+
+A v1 payload (with `name` and `age` only) decodes to a `Person` whose `email`
is `null`.
+Primitive fields added later default to `0`, `0.0`, or `false`. If a class
adopts versioning
+after its v1 is already in the wild, set `@ForySchema(baseVersion = N)` so
unannotated fields
+are treated as present since version `N`.
+
+Remove a field by deleting the Java member and declaring it on a nested
history interface as a
+method with a `@ForyVersion(until = N)`. The method's return type carries any
parameterized
+type information from the original field.
+
+```java
+@Data
+@ForySchema(removedFields = Person.History.class)
+public class Person {
+ private String name;
+
+ @ForyVersion(since = 2)
+ private String email;
+
+ interface History {
+ @ForyVersion(until = 3)
+ int age();
+
+ @ForyVersion(until = 5)
+ List<String> tags();
+ }
+}
+```
+
+The history method name matches the original live descriptor name: the field
name for Lombok
+`@Data` or records (`age`, `tags`), or the full accessor name for
JavaBeans-style classes and
+interfaces (`getAge`).
+
+### Wire format and limitations
+
+Producers and consumers must agree on the `withSchemaEvolution()` flag — they
are not
+wire-compatible otherwise. Row payloads always carry an 8-byte hash slot;
under evolution its
Review Comment:
what about the upgrade path?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
