This document provides some necessary points for developers to consider when writing and reviewing Ironic code. The checklist will help developers get things right.
If you’re completely new to OpenStack and want to contribute to the ironic project, please start by familiarizing yourself with the Infra Team’s Developer Guide. This will help you get your accounts set up in Launchpad and Gerrit, familiarize you with the workflow for the OpenStack continuous integration and testing systems, and help you with your first commit.
Most of the tools used for OpenStack require a launchpad.net ID for authentication. Ironic previously used to track work on Launchpad, but we have not done so since migrating to Storyboard.
See also
The ironic project moved from Launchpad to StoryBoard for work and task tracking. This provides an aggregate view called a “Project Group” and individual “Projects”. A good starting place is the project group representing the whole of the ironic community, as opposed to the ironic project storyboard which represents ironic as a repository.
Daily contributor discussions take place on IRC in the ‘#openstack-ironic’ channel on Freenode IRC.
Please feel free to join us at irc://irc.freenode.net and join our channel!
Ironic is a community of projects centered around the primary project repository ‘ironic’, which help facilitate the deployment and management of bare metal resources.
This means there are a number of different repositories that fall into the responsibility of the project team and the community. Some of the repositories may not seem strictly hardware related, but they may be tools or things to just make an aspect easier.
[ironic]
)Ironic tracks new features using RFEs (Requests for Feature Enhancements) instead of blueprints. These are stories with ‘rfe’ tag, and they should be submitted before a spec or code is proposed.
When a member of the ironic-core team decides that the proposal is worth implementing, a spec (if needed) and code should be submitted, referencing the RFE task or story ID number. 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.
We track our stories and tasks in Storyboard.
https://storyboard.openstack.org/#!/project/ironic
When working on an RFE, please be sure to tag your commits properly: “Story: #xxxx” or “Task: #xxxx”. It is also helpful to set a consistent review topic, such as “story/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 story for all the code you’re submitting, there is no need to create a separate RFE in every project.
Note
RFEs may only be approved by members of the ironic-core team.
Note
While not strictly required for minor changes and fixes, it is highly preferred by the Ironic community that any change which needs to be backported, have a recorded Story and Task in Storyboard.
If you would like some help, or if you (or some members of your team) are unable to continue working on the feature, updating and maintaining the changes, please let the rest of the ironic community know. You could leave a comment in one or more of the changes/patches, bring it up in IRC, the weekly meeting, or on the OpenStack development email list. Communicating this will make other contributors aware of the situation and allow for others to step forward and volunteer to continue with the work.
In the event that a contributor leaves the community, do not expect the contributor’s changes to be continued unless someone volunteers to do so.
Within the Ironic project, we generally require two core reviewers to sign-off (+2) change sets. We also will generally recognize non-core (+1) reviewers, and sometimes even reverse our decision to merge code based upon their reviews.
We recognize that some repositories have less visibility, as such it is okay to ask for a review in our IRC channel. Please be prepared to stay in IRC for a little while in case we have questions.
Sometimes we may also approve patches with a single core reviewer. This is generally discouraged, but sometimes necessary. When we do so, we try to explain why we do so. As a patch submitter, it equally helps us to understand why the change is important. Generally, more detail and context helps us understand the change faster.
As with any large project, it does take time for features and changes to be merged in any of the project repositories. This is largely due to limited review bandwidth coupled with varying reviewer priorities and focuses.
When establishing an understanding of complexity, the following things should be kept in mind.
Specifications must follow the template which can be found at specs/template.rst, which is quite self-documenting. Specifications are proposed by adding them to the specs/approved directory, adding a soft link to it from the specs/not-implemented directory, and posting it for review to Gerrit. For more information, please see the README.
The same Gerrit process as with source code, using the repository ironic-specs, is used to add new specifications.
All approved specifications are available at: https://specs.openstack.org/openstack/ironic-specs. If a specification has been approved but not completed within one or more releases since the approval, it may be re-reviewed to make sure it still makes sense as written.
Ironic specifications are part of the RFE (Requests for Feature Enhancements) process. You are welcome to submit patches associated with an RFE, but they will have a -2 (“do not merge”) until the specification has been approved. This is to ensure that the patches don’t get accidentally merged beforehand. You will still be able to get reviewer feedback and push new patch sets, even with a -2. The list of core reviewers for the specifications is small but mighty. (This is not necessarily the same list of core reviewers for code patches.)
For approved but not-completed specs:
For approved and completed specs:
Please see the Ironic specs process wiki page for further reference.
Bugs can reported via our Task and Bug tracking tool Storyboard.
When filing bugs, please include as much detail as possible, and don’t be shy.
Essential pieces of information are generally:
Please also set your expectations of what should be happening. Statements of user expectations are how we understand what is occuring and how we learn new use cases!
The Project Team Leader
or PTL
is elected each development
cycle by the contributors to the ironic community.
Think of this person as your primary contact if you need to try and rally the project, or have a major issue that requires attention.
They serve a role that is mainly oriented towards trying to drive the technical discussion forward and managing the idiosyncrasies of the project. With this responsibility, they are considered a “public face” of the project and are generally obliged to try and provide “project updates” and outreach communication.
All common PTL duties are enumerated here in the PTL guide.
Tasks like release management or preparation for a release are generally delegated with-in the team. Even outreach can be delegated, and specifically there is no rule stating that any member of the community can’t propose a release, clean-up release notes or documentation, or even get on the occasional stage.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.