openstack/api-sig
Code Issues Proposed changes

Add versioning guideline for API microversions

Browse Source 
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
This commit is contained in:
Ken'ichi Ohmichi
2015-11-26 08:23:39 +00:00
parent 48eb61fe21
commit b02c62a6bc
1 changed files with 34 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
guidelines/microversion_specification.rst
View File

@@ -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 <http://semver.org/>`_.
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
------------------