Update the readme for Auto-Common to more accurately reflect the stat…

…e of the project w.r.t. API stability. ------------- Created by MOE: http://code.google.com/p/moe-java MOE_MIGRATED_REVID=92939163
google · May 6, 2015 · acc0ea3 · acc0ea3
1 parent b1aca4d
commit acc0ea3
Showing 1 changed file with 57 additions and 3 deletions.
diff --git a/common/README.md b/common/README.md
@@ -3,18 +3,26 @@ Auto Common Utilities
 
 ## Overview
 
-The Auto project has a set of common utilities to help ease use of the annotation processing environment. 
+The Auto project has a set of common utilities to help ease use of the annotation processing
+environment.
 
 ## Utility classes of note
 
   * MoreTypes - utilities and Equivalence wrappers for TypeMirror and related subtypes
   * MoreElements - utilities for Element and related subtypes
-  * SuperficialValidation - very simple scanner to ensure an Element is valid and free from distortion from upstream compilation errors
+  * SuperficialValidation - very simple scanner to ensure an Element is valid and free from
+    distortion from upstream compilation errors
   * Visibility - utilities for working with Elements' visibility levels (public, protected, etc.)
+  * BasicAnnotationProcessor/ProcessingStep - simple types that
+    - implement a validating annotation processor
+    - defer invalid elements until later
+    - break processor actions into multiple steps (which may each handle different annotations)
 
 ## Usage/Setup
 
-Auto common utilities have a standard maven setup which can be used from Gradle, Ivy, Ant, or other systems which consume binary artifacts from the central maven repositories. 
+Auto common utilities have a standard [Maven](http://maven.apache.org) setup which can also be
+used from Gradle, Ivy, Ant, or other systems which consume binary artifacts from the central Maven
+binary artifact repositories.
 
 ```xml
 <dependency>
@@ -23,3 +31,49 @@ Auto common utilities have a standard maven setup which can be used from Gradle,
   <version>1.0-SNAPSHOT</version> <!-- or use a known release version -->
 </dependency>
 ```
+
+## Processor Resilience
+
+Auto Common Utilities is used by a variety of annotation processors in Google and new versions
+may have breaking changes.  Users of auto-common are urged to use
+[shade](https://maven.apache.org/plugins/maven-shade-plugin/) or
+[jarjar](https://code.google.com/p/jarjar/) (or something similar) in packaging their processors
+so that conflicting versions of this library do not adversely interact with each other.
+
+For example, in a Maven build you can repackage `com.google.auto.common` into
+`your.processor.shaded.auto.common` like this:
+
+```xml
+<project>
+  <!-- your other config -->
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-shade-plugin</artifactId>
+        <executions>
+          <execution>
+            <phase>package</phase>
+            <goals>
+              <goal>shade</goal>
+            </goals>
+            <configuration>
+              <artifactSet>
+                <excludes>
+                  <!-- exclude dependencies you don't want to bundle in your processor -->
+                </excludes>
+              </artifactSet>
+              <relocations>
+                <relocation>
+                  <pattern>com.google.auto.common</pattern>
+                  <shadedPattern>your.processor.shaded.auto.common</shadedPattern>
+                </relocation>
+              </relocations>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+```
+