api evolution

Author: hauner

docs/modules/ROOT/pages/index.adoc

@@ -41,6 +41,49 @@ the plugins will call `void run(Map<String, ?> options);` to run the processor,
 
 - provide a `META-INF/services/io.openapiprocessor.api.OpenApiProcessor` property file in the resources with the class name of the implementing class.
 
+== api evolution
+
+[cols="5*",options="header"]
+|===
+| api version
+| package name
+| gradle plugin
+| maven plugin
+| description
+
+| 2020.3 (1.3.0)
+| `io.openapiprocessor.api.v1.OpenApiProcessor`
+| yes
+| no
+a| unchanged
+
+| 2020.3 (1.3.0)
+| `io.openapiprocessor.api.v1.Version`
+| no
+| no
+a| *experimental* to query a processor version
+
+| 1.2.0
+| `io.openapiprocessor.api.v1.OpenApiProcessor`
+| yes
+| no
+a| better package name, no other changes
+
+| 1.1.0
+| `io.openapiprocessor.api.OpenApiProcessor`
+| yes
+| no
+a| new package name
+
+//4+| &darr; old (deprecated)
+
+| 1.0.0
+| `com.github.hauner.openapi.api.OpenApiProcessor`
+| yes
+| yes
+a| old package name, still used by all processors
+
+|===
 
 == example implementations