Ironic/Developer guidelines

= Guidelines for Developers =

The developer documentation provides a good starting point. This provides miscellaneous guidelines for doing development.

Exceptions
For the most part, ironic should only be raising ironic exceptions. In particular:
 * drivers should handle (non-ironic exceptions) and only let ironic exceptions be raised
 * internal methods do not need to have docstrings (although rloo does like them)
 * public methods need to have docstrings and include ":raises:" for all known exceptions that can be raised by that method (or any methods invoked by that method)

Backwards compatibility
We need to make sure we don't unintentionally break backwards compatibility.

Areas this is important:
 * REST API. Previous releases of the client must not be severely broken by changes in the same major (eg, /v1/) version of the API. This is true even with microversions.
 * Driver API. We encourage the use of out-of-tree drivers. Any change to the driver api, defined in /ironic/drivers/base.py, must be backwards-compatible. Significant changes may be handled by a deprecation cycle.

Some things to watch out for:
 * exception names. If you want to change the name of an exception class, please add an alias for the original name. The commit should have a DocImpact flag, with a description of what is deprecated, when it will be removed, and what to use instead (if anything).

Deprecations
Ironic follows OpenStack's standard deprecation process. If something is going to be deprecated, we need to:
 * inform the Ironic community (via email) that it is deprecated and when it will be removed
 * during the deprecation period, if it makes sense, we should warn and/or log any uses of the deprecated thing
 * at least one release cycle should be given between deprecation and removal, AND a minimum of 3 months must have elapsed
 * After it has been removed, inform the Ironic community (via email)

Tempest tests
[Tempest] tests are black-box functionality tests. [Ironic uses tempest] for API and functional testing.

If your change includes significant API visible functionality, there should be corresponding tempest test coverage. Eg anything that the nova.virt.ironic driver does. The developer responsible for the code changes is also responsible for ensuring that there is tempest test coverage. (The developer doesn't have to make the tempest test changes; they could work with another developer to help write the tempest tests.)

Tempest is run via devstack, where the latest master branch of Ironic is cloned and then tests are run against it. So changes have to be in Ironic before the tempest test can pass. The suggested process is:
 * code changes ready for review
 * corresponding tempest changes ready for review
 * the code changes may be blocked from being approved if there are no corresponding tempest changes
 * after the code changes have been merged, the tempest changes will be merged. If the tempest tests fail, we'll all scream.

diagrams

 * for the specs, http://asciiflow.com is used, so we decided to use the same for our ironic documentation

*recheck*ing on failed CI tests

 * Examine the logs uploaded from the CI tests to see if the problem is related to your change.
 * If you feel it isn't, check if the problem is already reported before in http://status.openstack.org/elastic-recheck/
 * If you find it's a know issue, post a comment on the gerrit review "recheck bug " where  is the numerical identifier for bug. For example "recheck bug 1408067".  This also helps in tracking how many times same issue is hit in a day.
 * If you cannot find the bug #, you have following options:
 * Read through http://docs.openstack.org/infra/elastic-recheck/readme.html#adding-bug-signatures and try to find the bug # related to it.
 * Check in #openstack-ironic IRC to see if someone knows about this
 * Last option, post a comment with just "recheck" on gerrit.