update runtime docs to give info on upgrading

darshan-runtime/doc/darshan-runtime.txt

@@ -466,6 +466,38 @@ older versions of Open MPI, please refer to the following mailing list discussio
 
 http://www.open-mpi.org/community/lists/devel/2013/01/11907.php
 
+== Upgrading to Darshan 3.x from 2.x
+
+Beginning with Darshan 3.0.0, Darshan has been rewritten to modularize its runtime environment
+and log file format to simplify the addition of new I/O characterization data. The process of
+compiling and installing the Darshan 3.x source code should essentially be identical to this
+process on Darshan 2.x. Therefore, the installation recipes given in the previous section
+should work irrespective of the Darshan version being used. Similarly, the manner in which
+Darshan is used should be the same across versions -- the sections in this document regarding
+Darshan link:darshan-runtime.html#_environment_preparation[environment preparation],
+instrumenting link:darshan-runtime.html#_instrumenting_statically_linked_applications[statically
+linked applications] and link:darshan-runtime.html#_instrumenting_dynamically_linked_applications[
+dynamically linked applications], and using link:darshan-runtime.html#_runtime_environment_variables[
+runtime environment variables] are equally applicable to both versions.
+
+However, we do provide some suggestions and expectations for system administrators to keep in
+mind when upgrading to Darshan 3.x:
+
+* Log file compatibility was broken in the upgrade, and thus 3.x log utilities do not
+work directly with logs generated by 2.x versions of Darshan (and vice versa).
+    - There is currently no tool for converting 2.x logs into the 3.x log format
+
+* The darshan log file extension has been changed from `.darshan.gz` (or `.darshan.bz2` for
+log files converted to use bzip2 compression) to `.darshan`
+    - A field in the Darshan log header is used to indicate whether a log is compressed using
+libz or bzip2 compression.
+
+* We encourage administrators to use the same log file directory for version 3.x as had been
+used for version 2.x.
+    - Within this directory, the determination on which set of log utilities (version 2.x
+or version 3.x) to use can be based on the file extension for a given log (as explained
+above)
+
 == Runtime environment variables
 
 The Darshan library honors the following environment variables to modify