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

.. _code-contribution-guide:

=======================
Code Contribution Guide
=======================

This document provides some necessary points for developers to consider when
writing and reviewing Ironic code. The checklist will help developers get
things right.

Adding new features
===================

Starting with the Mitaka development cycle, Ironic tracks new features using
RFEs (Requests for Feature Enhancements) instead of blueprints. These are bugs
with 'rfe' tag, and they should be submitted before a spec or code is proposed.
When a member of `ironic-drivers launchpad team
<https://launchpad.net/~ironic-drivers/+members>`_ decides that the proposal
is worth implementing, a spec (if needed) and code should be submitted,
referencing the RFE bug. Contributors are welcome to submit a spec and/or code
before the RFE is approved, however those patches will not land until the RFE
is approved.

Here is a list of steps to do during the new process of adding a new feature to
Ironic:

#. Submit a bug report at https://bugs.launchpad.net/ironic/+filebug.
   There are two fields that must be filled: 'summary' and
   'further information'. The 'summary' must be brief enough to fit in one
   line: if you can’t describe it in a few words it may mean that you are
   either trying to capture more than one RFE at once, or that you are having
   a hard time defining what you are trying to solve at all.

#. Describe the proposed change in the 'further information' field. The
   description should provide enough details for a knowledgeable developer to
   understand what is the existing problem in the current platform that needs
   to be addressed, or what is the enhancement that would make the platform
   more capable, both from a functional and a non-functional standpoint.

#. Submit the bug, add an 'rfe' tag to it and assign yourself or whoever is
   going to work on this feature.

#. As soon as a member of the ironic-drivers team acknowledges the bug, it
   will be moved into the 'Triaged' state. The importance will be set to
   'Wishlist' to signal the fact that the report is indeed a feature and there
   is no severity associated to it. Discussion about the RFE, and whether to
   approve it, happens in bug comments while in the 'Triaged' state.

#. The ironic-drivers team will evaluate the RFE and may advise the submitter
   to file a spec in ironic-specs to elaborate on the feature request, in case
   the RFE requires extra scrutiny, more design discussion, etc. For the spec
   submission process, please see the
   `specs process <https://wiki.openstack.org/wiki/Ironic/Specs_Process>`_
   wiki page.

#. If a spec is not required, once the discussion has happened and there is
   positive consensus among the ironic-drivers team on the RFE, the RFE is
   'approved', and its tag will move from 'rfe' to 'rfe-approved'. This means
   that the feature is approved and the related code may be merged.

#. If a spec is required, the spec must be submitted (with the bug properly
   referenced as 'Partial-Bug' in the commit message), reviewed, and merged
   before the RFE will be 'approved' (and the tag changed to 'rfe-approved').

#. The bug then goes through the usual process -- first to 'In progress' when
   the spec/code is being worked on, then 'Fix Released' when it is
   implemented.

#. If the RFE is rejected, the ironic-drivers team will move the bug to
   "Won't Fix" status.

When working on an RFE, please be sure to tag your commits properly:
"Partial-Bug: #xxxx" or "Related-Bug: #xxxx" for intermediate commits for the
feature, and "Closes-Bug: #xxxx" for the final commit. It is also helpful to
set a consistent review topic, such as "bug/xxxx" for all patches related to
the RFE.

If the RFE spans across several projects (e.g. ironic and python-ironicclient),
but the main work is going to happen within ironic, please use the same bug for
all the code you're submitting, there is no need to create a separate RFE in
every project.

Note that currently the Ironic bug tracker is managed by the open 'ironic-bugs'
team, not the ironic-drivers team. This means that anyone may edit bug details,
and there is room to game the system here. **RFEs may only be approved by
members of the ironic-drivers team**. Attempts to sneak around this rule will
not be tolerated, and will be called out in public on the mailing list.


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:

 - The RPC version must be incremented and be the same value for both the client
   (conductor/rpcapi.py, used by ironic-api) and the server (conductor/manager.py,
   used by ironic-conductor).
 - 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 supported.
 - 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
   signatures 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.