Document versioning and stability of programming interfaces

Author: acogoluegnes

src/docs/asciidoc/index.adoc

@@ -85,6 +85,37 @@ repositories {
 }
 ----
 
+== Versioning
+
+The RabbitMQ AMQP 1.0 Java Client is in development and stabilization phase.
+When the stabilization phase ends, a 1.0.0 version will be cut, and
+https://semver.org/[semantic versioning] is likely to be enforced.
+
+Before reaching the stable phase, the client will use a versioning scheme of `[0.MINOR.PATCH]` where:
+
+* `0` indicates the project is still in a stabilization phase.
+* `MINOR` is a 0-based number incrementing with each new release cycle. It generally reflects significant changes like new features and potentially some programming interfaces changes.
+* `PATCH` is a 0-based number incrementing with each service release, that is bux fixes.
+
+Breaking changes between releases can happen but will be kept to a minimum.
+The next section provides more details about the evolution of programming interfaces.
+
+[[stability-of-programming-interfaces]]
+== Stability of Programming Interfaces
+
+The RabbitMQ AMQP 1.0 Java Client is in active development but its programming interfaces will remain as stable as possible. There is no guarantee though that they will remain completely stable, at least until it reaches version 1.0.0.
+
+The client contains 2 sets of programming interfaces whose stability are of interest for application developers:
+
+* Application Programming Interfaces (API): those are the ones used to write application logic.
+They include the interfaces and classes in the `com.rabbitmq.client.amqp` package (e.g. `Connection`, `Publisher`, `Consumer`, `Message`).
+These API constitute the main programming model of the client and will be kept as stable as possible.
+* Service Provider Interfaces (SPI): those are interfaces to implement mainly technical behavior in the client.
+They are not meant to be used to implement application logic.
+Application developers may have to refer to them in the configuration phase and if they want to customize some internal behavior of the client.
+SPI packages and interfaces are marked as such in their Javadoc.
+_These SPI are susceptible to change, but this should have no impact on most applications_, as the changes are likely to be limited to the client internals.
+
 include::usage.adoc[]
 
 include::appendixes.adoc[]