Merge "Add Code Contribution Guide for Ironic"

doc/source/dev/code-contribution-guide.rst

@@ -0,0 +1,56 @@
+.. _code-contribution-guide:
+
+==================================
+Code Contribution Guide for Ironic
+==================================
+
+This document provides some necessary points for developers to consider when
+writing and reviewing Ironic code. The checklist will help developers get things
+right.
+
+Live Upgrade Related Concerns
+=============================
+Ironic implements upgrade with the same methodology of Nova:
+    http://docs.openstack.org/developer/nova/upgrade.html
+
+Ironic API RPC Versions
+-----------------------
+
+*  When the signature(arguments) of an RPC method is changed, the following things
+   need to be considered:
+
+ - Client-side (conductor/rpcapi.py) and server-side (conductor/manager.py)
+   should both increment the RPC version by one and the RPC versions must be the same of
+   the client and server.
+ - New arguments of the method can only be added as optional. Existing arguments cannot be
+   removed or changed in incompatible ways (with the method in older RPC versions).
+ - Client-side can pin a version cap by passing ``version_cap`` to the constructor
+   of oslo_messaging.RPCClient. Methods which change arguments should run
+   client.can_send_version() to see if the version of the request is compatible with the
+   version cap of RPC Client, otherwise the request needs to be created to work with a
+   previous version that is suppoted.
+ - Server-side should tolerate the older version of requests in order to keep
+   working during the progress of live upgrade. The behavior of server-side should
+   depend on the input parameters passed from the client-side.
+
+Object Versions
+---------------
+* When Object classes (subclasses of ironic.objects.base.IronicObject) are modified, the
+  following things need to be considered:
+
+ - The change of fields and the signature of remotable method needs a bump of object
+   version.
+ - The arguments of methods can only be added as optional, they cannot be
+   removed or changed in an incompatible way.
+ - Fields types cannot be changed. If it is a must, create a new field and
+   deprecate the old one.
+ - When new version objects communicate with old version objects,
+   obj_make_compatible() will be called to convert objects to the target version during
+   serialization. So objects should implement their own obj_make_compatible() to
+   remove/alter attributes which was added/changed after the target version.
+ - There is a test (object/test_objects.py) to generate the hash of object fields and the
+   signtures of remotable methods, which helps developers to check if the change of
+   objects need a version bump. The object fingerprint should only be updated with a
+   version bump.
+
+

doc/source/index.rst

@@ -64,6 +64,7 @@ Introduction
   dev/architecture
   dev/states
   dev/contributing
+  dev/code-contribution-guide
 
 .. toctree::
   dev/dev-quickstart