From 0d906937d6589f7badfde653a7988edfe6f96a17 Mon Sep 17 00:00:00 2001 From: Mark McLoughlin Date: Sun, 4 Aug 2013 07:02:06 +0100 Subject: [PATCH] Add some docs on target version numbers This is advice copied from oslo-incubator's dispatcher.py. Change-Id: Ib0fe7e4734eaefe177d022389df75f7bf8ee5e6a --- doc/source/target.rst | 47 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/doc/source/target.rst b/doc/source/target.rst index ab4b72ba9..047a8e357 100644 --- a/doc/source/target.rst +++ b/doc/source/target.rst @@ -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.