From b02c62a6bc3dfd215363bb70954dd0e0789a2b05 Mon Sep 17 00:00:00 2001 From: Ken'ichi Ohmichi Date: Thu, 26 Nov 2015 08:23:39 +0000 Subject: [PATCH] Add versioning guideline for API microversions This versioning way is different from common versioning way SemVer, and most people are confused when seeing the API microversions at the first time. So it is nice to discuss this versioning way for the guideline. Change-Id: If0371eac346de1c4bad8086e642926f71175b94b --- guidelines/microversion_specification.rst | 35 ++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/guidelines/microversion_specification.rst b/guidelines/microversion_specification.rst index e9e3f7d..7bbbd02 100644 --- a/guidelines/microversion_specification.rst +++ b/guidelines/microversion_specification.rst @@ -13,7 +13,40 @@ servers, clients adjust their behavior to work with server correctly. Versioning ---------- -TBD +Versioning of the API should be single monotonic counter taking the form +X.Y following these conventions: + +* X should only be changed if a significant backwards incompatible + API change is made which affects the API as whole. That is, something + that is only very rarely incremented. X should be changed in the following + cases. + ** A number of endpoints get replaced by others + ** Drastic changes in API consumer workflow +* Y should be changed when you make any change to the API. Note that this + includes semantic changes which may not affect the input or output formats or + even originate in the API code layer. We are not distinguishing + between backwards compatible and backwards incompatible changes in + the versioning system. It will however be made clear in the + documentation as to what is a backwards compatible change and what + is a backwards incompatible one. + +.. note:: Note that these versions numbers do not follow the rules of + `Semantic Versioning `_. + +There are minimum and maximum versions which are used to describe what the +server can understand. The minimum and maximum versions are the oldest and +most recent versions supported. So clients can specify different version in +the supporting range for each API call on the same server. The minimum version +can be increased when supporting old clients is too great a burden. +Increasing the minimum version means breaking the old clients, this happens +very rarely also. + +Each version includes all the changes since minimum version was introduced. +It is not possible to request the feature introduced at microversion X.Y +without accepting all the changes before X.Y in the same request. +For example, you cannot request the feature which was introduced at +microversion 2.100 without backwards incompatible changes which were +introduced in microversion 2.99 and earlier. Client Interaction ------------------