Add compatibility notice for Java.
diff --git a/java/README.md b/java/README.md
index 060d9ac..83f91e1 100644
--- a/java/README.md
+++ b/java/README.md
@@ -17,9 +17,10 @@
http://maven.apache.org/
-2) Build the C++ code, or obtain a binary distribution of protoc. If
- you install a binary distribution, make sure that it is the same
- version as this package. If in doubt, run:
+2) Build the C++ code, or obtain a binary distribution of protoc (see
+ the toplevel [README.md](../README.md)). If you install a binary
+ distribution, make sure that it is the same version as this package.
+ If in doubt, run:
$ protoc --version
@@ -44,36 +45,25 @@
The .jar will be placed in the "target" directory.
-Installation - 'Lite' Version - With Maven
-==========================================
+The above instructions will install 3 maven artifacts:
-Building the 'lite' version of the Java Protocol Buffers library is
-the same as building the full version, except that all commands are
-run using the 'lite' profile. (see
-http://maven.apache.org/guides/introduction/introduction-to-profiles.html)
-
-E.g. to install the lite version of the jar, you would run:
-
- $ mvn install -P lite
-
-The resulting artifact has the 'lite' classifier. To reference it
-for dependency resolution, you would specify it as:
-
-```
- <dependency>
- <groupId>com.google.protobuf</groupId>
- <artifactId>protobuf-java</artifactId>
- <version>${version}</version>
- <classifier>lite</classifier>
- </dependency>
-```
+ * protobuf-java: The core Java Protocol Buffers library. Most users only
+ need this artifact.
+ * protobuf-lite: The lite version of core Java Protobuf Buffers library. It
+ is a subset of the core library and is used together with
+ the 'lite' code generator flag to reduce generated code size
+ for mobile.
+ * protobuf-java-util: Utilities to work with protos. It contains JSON support
+ as well as utilities to work with proto3 well-known
+ types.
Installation - Without Maven
============================
If you would rather not install Maven to build the library, you may
follow these instructions instead. Note that these instructions skip
-running unit tests.
+running unit tests and only describes how to install the core protobuf
+library (without the util package).
1) Build the C++ code, or obtain a binary distribution of protoc. If
you install a binary distribution, make sure that it is the same
@@ -86,15 +76,50 @@
2) Invoke protoc to build DescriptorProtos.java:
- $ protoc --java_out=src/main/java -I../src \
+ $ protoc --java_out=core/src/main/java -I../src \
../src/google/protobuf/descriptor.proto
-3) Compile the code in src/main/java using whatever means you prefer.
+3) Compile the code in core/src/main/java using whatever means you prefer.
4) Install the classes wherever you prefer.
-Usage
-=====
+Compatibility Notice
+====================
+
+* Protobuf minor version releases are backwards-compatible. If your code
+ can build/run against the old version, it's expected to build/run against
+ the new version as well. Both binary compatibility and source compatbility
+ are guaranteed for minor version releases if the user follows the guideline
+ described in this section.
+
+* Protobuf major version releases may also be backwards-compatbile with the
+ last release of the previous major version. See the release notice for more
+ details.
+
+* APIs marked with the @ExperimentalApi annotation are subject to change. They
+ can be modified in any way, or even removed, at any time. Don't use them if
+ compatiblity is needed. If your code is a library itself (i.e. it is used on
+ the CLASSPATH of users outside your own control), you should not use
+ experimental APIs, unless you repackage them (e.g. using ProGuard).
+
+* Deprecated non-experimental APIs will be removed two years after the release
+ in which they are first deprecated. You must fix your references before this
+ time. If you don't, any manner of breakage could result (you are not
+ guaranteed a compilation error).
+
+* Protobuf message interfaces/classes are designed to be subclassed by protobuf
+ generated code only. Do not subclass these message interfaces/classes
+ yourself. We may add new methods to the message interfaces/classes which will
+ break your own subclasses.
+
+* Don't use any method/class that is marked as "used by generated code only".
+ Such methods/classes are subject to change.
+
+* Protobuf LITE runtime APIs are not stable yet. They are subject to change even
+ in minor version releases.
+
+Documentation
+=============
The complete documentation for Protocol Buffers is available via the
web at:
