Introduce a compatibility promise

README.md

@@ -273,3 +273,26 @@ The above code prints the following output:
    Target type:@Label(value = "Name") java.lang.String
    Equivalent? true
 ```
+
+## Compatibility Promise
+
+Jandex uses an `X.Y.Z` versioning scheme.
+In the following text, we call `X` a _major_ version, `Y` a _minor_ version, and `Z` a _micro_ version.
+
+### API
+
+Jandex may break backward compatibility for _callers_ of the Jandex API in major versions.
+If you only call Jandex API, updating to a newer minor or micro version is safe.
+
+Jandex may break backward compatibility for users that _extend_ Jandex classes or _implement_ Jandex interfaces in minor or major versions.
+If you extend Jandex classes or implement Jandex interfaces, updating to a newer micro version is safe.
+
+### Persistent Index Format
+
+The persistent index format is versioned.
+Jandex is backward compatible when it comes to reading the persistent index, but not forward compatible.
+In other words, newer Jandex can read older index, but older Jandex can't read newer index.
+
+Jandex may introduce a new persistent index format version in minor or major versions.
+If you distribute a Jandex index as part of your artifacts, updating to a newer micro version is safe.
+Updating to a newer minor or major version may require consumers of the Jandex index to also update.

src/main/java/org/jboss/jandex/IndexReader.java

@@ -84,7 +84,10 @@ private void initReader(int version) throws IOException {
             reader = new IndexReaderV2(input);
         } else {
             input.close();
-            throw new UnsupportedVersion("Version: " + version);
+            throw new UnsupportedVersion("Can't read index version " + version
+                    + "; this IndexReader only supports index versions "
+                    + IndexReaderV1.MIN_VERSION + "-" + IndexReaderV1.MAX_VERSION + ","
+                    + IndexReaderV2.MIN_VERSION + "-" + IndexReaderV2.MAX_VERSION);
         }
 
         this.reader = reader;

src/main/java/org/jboss/jandex/IndexWriter.java

@@ -101,7 +101,10 @@ public int write(Index index, int version) throws IOException {
 
         IndexWriterImpl writer = getWriter(version);
         if (writer == null) {
-            throw new UnsupportedVersion("Version: " + version);
+            throw new UnsupportedVersion("Can't write index version " + version
+                    + "; this IndexWriter only supports index versions "
+                    + IndexWriterV1.MIN_VERSION + "-" + IndexWriterV1.MAX_VERSION + ","
+                    + IndexWriterV2.MIN_VERSION + "-" + IndexWriterV2.MAX_VERSION);
         }
 
         return writer.write(index, version);

src/main/java/org/jboss/jandex/IndexWriterV1.java

@@ -98,7 +98,9 @@ final class IndexWriterV1 extends IndexWriterImpl {
     int write(Index index, int version) throws IOException {
 
         if (version < MIN_VERSION || version > MAX_VERSION) {
-            throw new UnsupportedVersion("Version: " + version);
+            throw new UnsupportedVersion("Can't write index version " + version
+                    + "; this IndexWriterV1 only supports index versions "
+                    + IndexWriterV1.MIN_VERSION + "-" + IndexWriterV1.MAX_VERSION);
         }
 
         PackedDataOutputStream stream = new PackedDataOutputStream(new BufferedOutputStream(out));

src/main/java/org/jboss/jandex/IndexWriterV2.java

@@ -183,7 +183,9 @@ int size() {
     int write(Index index, int version) throws IOException {
 
         if (version < MIN_VERSION || version > MAX_VERSION) {
-            throw new UnsupportedVersion("Version: " + version);
+            throw new UnsupportedVersion("Can't write index version " + version
+                    + "; this IndexWriterV2 only supports index versions "
+                    + IndexWriterV2.MIN_VERSION + "-" + IndexWriterV2.MAX_VERSION);
         }
 
         PackedDataOutputStream stream = new PackedDataOutputStream(new BufferedOutputStream(out));