Add some usage documentation.

1 files changed, 56 insertions, 0 deletions

diff --git a/abi-check-plugin/README.md b/abi-check-plugin/README.md
new file mode 100644
index 00000000000..23a68a94783
--- /dev/null
+++ b/abi-check-plugin/README.md
@@ -0,0 +1,56 @@
+# abi-check-plugin
+
+Maven plugin for ensuring project ABI stability.
+
+## Theory of operation
+
+The project artifact JAR is scanned for class files. The resulting package tree is scanned for
+packages annotated with configured annotation denoting a package that is considered public ABI.
+Classes in those packages are scanned for their visible ABI and the result is compared against
+expected ABI (stored in a JSON file) and possible discrepancies are reported.
+
+## What is considered visible ABI
+
+Visible ABI is considered to be classes, methods and fields that are accessible from other JAR
+files without use of reflection or other tricks.
+
+## Setup
+
+### Add plugin to build
+
+Add the plugin to `<plugins>` in the project `pom.xml`, with an execution of `abicheck` goal. This
+goal has to be executed in a phase where the project artifact JAR is available, the recommended
+phase is `package`.
+
+Example:
+```
+<plugin>
+  <groupId>com.yahoo.vespa</groupId>
+  <artifactId>abi-check-plugin</artifactId>
+  <configuration>
+    <publicApiAnnotation>com.yahoo.api.annotations.PublicApi</publicApiAnnotation>
+  </configuration>
+  <executions>
+    <execution>
+      <phase>package</phase>
+        <goals>
+          <goal>abicheck</goal>
+        </goals>
+    </execution>
+  </executions>
+</plugin>
+```
+
+### Configuration parameters
+
+ * **publicApiAnnotation** (required)  
+   Fully qualified class name of the annotation that denotes a public API package.
+ * **specFileName** (optional, default: `abi-spec.json`)  
+   File name relative to project root from which to read the expected ABI spec from.
+   
+## Updating the expected ABI spec
+
+To automatically generate the expected ABI spec from the current ABI of the project, define
+property `abicheck.writeSpec` when running the relevant phase.
+
+Example: `mvn package -Dabicheck.writeSpec`