More information on format upgrades in Javadoc.

core/src/main/java/hudson/XmlFile.java

@@ -26,13 +26,13 @@ package hudson;
 import com.thoughtworks.xstream.XStream;
 import com.thoughtworks.xstream.converters.ConversionException;
 import com.thoughtworks.xstream.converters.Converter;
+import com.thoughtworks.xstream.converters.UnmarshallingContext;
 import com.thoughtworks.xstream.io.StreamException;
 import com.thoughtworks.xstream.io.xml.XppDriver;
-import com.thoughtworks.xstream.io.xml.XppReader;
+import hudson.diagnosis.OldDataMonitor;
 import hudson.model.Descriptor;
 import hudson.util.AtomicFileWriter;
 import hudson.util.IOException2;
-import hudson.util.IOUtils;
 import hudson.util.XStream2;
 import org.xml.sax.Attributes;
 import org.xml.sax.InputSource;
@@ -93,6 +93,11 @@ import java.util.logging.Logger;
  * old fields will be never written back.)
  *
  * <p>
+ * You may also want to call {@link OldDataMonitor#report(UnmarshallingContext, String)}.
+ * This can be done within a nested class {@code ConverterImpl} extending {@link hudson.util.XStream2.PassthruConverter}
+ * in an override of {@link hudson.util.XStream2.PassthruConverter#callback}.
+ *
+ * <p>
  * In some limited cases (specifically when the class is the root object
  * to be read from XML, such as {@link Descriptor}), it is possible
  * to completely and drastically change the data format. See
@@ -102,6 +107,7 @@ import java.util.logging.Logger;
  * There's a few other possibilities, such as implementing a custom
  * {@link Converter} for XStream, or {@link XStream#alias(String, Class) registering an alias}.
  *
+ * @see <a href="https://wiki.jenkins-ci.org/display/JENKINS/Architecture#Architecture-Persistence">Architecture » Persistence</a>
  * @author Kohsuke Kawaguchi
  */
 public final class XmlFile {