openstack/oslo.messaging
Code Issues Proposed changes

Add some docs on target version numbers

Browse Source 
This is advice copied from oslo-incubator's dispatcher.py.

Change-Id: Ib0fe7e4734eaefe177d022389df75f7bf8ee5e6a
This commit is contained in:
Mark McLoughlin 2013-08-04 07:02:06 +01:00
parent 03fcbe6ca6
commit 0d906937d6
1 changed files with 47 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
doc/source/target.rst
View File

@ -5,3 +5,50 @@ Target
.. currentmodule:: oslo.messaging
.. autoclass:: Target
===============
Target Versions
===============
Target version numbers take the form Major.Minor. For a given message with
version X.Y, the server must be marked as able to handle messages of version
A.B, where A == X and B >= Y.
The Major version number should be incremented for an almost completely new
API. The Minor version number would be incremented for backwards compatible
changes to an existing API. A backwards compatible change could be something
like adding a new method, adding an argument to an existing method (but not
requiring it), or changing the type for an existing argument (but still
handling the old type as well).
If no version is specified it defaults to '1.0'.
In the case of RPC, if you wish to allow your server interfaces to evolve such
that clients do not need to be updated in lockstep with the server, you should
take care to implement the server changes in a backwards compatible and have
the clients specify which interface version they require for each method.
Adding a new method to an endpoint is a backwards compatible change and the
version attribute of the endpoint's target should be bumped from X.Y to X.Y+1.
On the client side, the new RPC invocation should have a specific version
specified to indicate the minimum API version that must be implemented for the
method to be supported. For example::
def get_host_uptime(self, ctxt, host):
cctxt = self.client.prepare(server=host, version='1.1')
return cctxt.call(ctxt, 'get_host_uptime')
In this case, version '1.1' is the first version that supported the
get_host_uptime() method.
Adding a new parameter to an RPC method can be made backwards compatible. The
endpoint version on the server side should be bumped. The implementation of
the method must not expect the parameter to be present.::
def some_remote_method(self, arg1, arg2, newarg=None):
# The code needs to deal with newarg=None for cases
# where an older client sends a message without it.
pass
On the client side, the same changes should be made as in example 1. The
minimum version that supports the new parameter should be specified.