Document intent to remove Serializable from CSVRecord.

aherbert · aherbert · commit 70092bb303af · 2020-01-28T10:33:51.000Z
This was added to the class header and the changes.xml for inclusion in
the release notes.
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -38,7 +38,12 @@
     <title>Apache Commons CSV Release Notes</title>
   </properties>
   <body>
-    <release version="1.8" date="2019-01-DD" description="Feature and bug fix release (Java 8)">
+    <release version="1.8" date="2019-01-DD" description="Feature and bug fix release (Java 8).
+
+This release fixes serialization compatibility of CSVRecord with versions 1.0 to 1.6.
+New fields added since 1.7 are not serialized. Support for Serializable is scheduled to be
+removed in version 2.0.
+">
       <action issue="CSV-255" type="add" dev="ggregory" due-to="0x100">Add CSVRecord.isSet(int) method #52.</action>
       <action issue="CSV-135" type="fix" dev="sebb" due-to="Mateusz Zakarczemny">Char escape doesn't work properly with quoting.</action>
       <action issue="CSV-244" type="fix" dev="sebb">Test case failures following CSVFormat#equals() update.</action>
diff --git a/src/main/java/org/apache/commons/csv/CSVRecord.java b/src/main/java/org/apache/commons/csv/CSVRecord.java
@@ -28,6 +28,15 @@
 
 /**
  * A CSV record parsed from a CSV file.
+ *
+ * <p>
+ * Note: Support for {@link Serializable} is scheduled to be removed in version 2.0.
+ * In version 1.8 the mapping between the column header and the column index was
+ * removed from the serialised state. The class maintains serialization compatibility
+ * with versions pre-1.8 for the record values; these must be accessed by index
+ * following deserialization. There will be loss of any functionally linked to the header
+ * mapping when transferring serialised forms pre-1.8 to 1.8 and vice versa.
+ * </p>
  */
 public final class CSVRecord implements Serializable, Iterable<String> {
 
@@ -46,7 +55,7 @@ public final class CSVRecord implements Serializable, Iterable<String> {
     /** The values of the record */
     private final String[] values;
 
-    /** The parser that originates this record. */
+    /** The parser that originates this record. This is not serialized. */
     private final transient CSVParser parser;
 
     CSVRecord(final CSVParser parser, final String[] values, final String comment, final long recordNumber,
