Jump to: navigation, search

Fuel/How to contribute

< Fuel
Revision as of 13:20, 8 October 2014 by Bogdan Dobrelya (talk | contribs) (Writing Documentation)

Join the Fuel team

First steps

First commits

  • Check out this short and simple guide on how to get started: How to contribute. Though it is for Rally, it still applies to any other OpenStack project, including Fuel.
  • How_To_Contribute page covers many more details, including bug fixes, etc. - and that's can be simply applied to Fuel related components.

How and where to get help

Subscribe to mailing lists

  • OpenStack developers mailing list. If you are hacking on Fuel, or have technical question about Fuel internals, you are very welcome in this ML with subject containing "[Fuel]".
  • OpenStack users mailing list. Fuel traffic is there with subject containing "[Fuel]". You are welcome to ask questions related to Fuel usage, including errors, etc.
  • OpenStack announcements mailing list. Announcements about the OpenStack project like product release information, security advisories, important discussions. This is a low-traffic, read-only list.
  • There are even more mailing lists out there, visit MailingLists to see the other OpenStack related lists.

IRC at freenode.net

  • The general Fuel channel is called "#fuel", and it is logged here.
  • The Fuel development channel is called "#fuel-dev", and it is logged here.

Quick reference dev links


Fuel is large project within which Programming, Linux and Networking intersect. It is written in Python, Ruby and JavaScript. It also has a number of build scripts in bash & make. Documentation is written in Sphinx. New contributors are always welcome.

Fuel development environments


The quickest way to get started with Fuel is to set up an environment under VirtualBox. This is a great way start testing, for instance by using the nightly builds to try to verify, confirm or triage bugs. A quick-start script and instructions can be found at https://software.mirantis.com/quick-start/.

Fuel ISO-build and development environment

Setting up an environment to build the Fuel ISO will allow you to easily build against specific commits in order to do more complicated bug test/confirm/triage/fix work, or augmenting Fuel with new features. In addition to preparing the environment for ISO building, the steps necessary to prepare a dev environment for the other Fuel components (nailgun, astute and doc building) can be found there. Instructions for preparing the environment can be found at http://docs.mirantis.com/fuel-dev/develop/env.html.

Fuel DevOps Environment

Setting up a Linux machine as a Fuel DevOps environment will allow you to automate the build/verify/test process, in addition to building the ISO and doing other Fuel-related development. Using libvirt, the devops environment is able to deploy multiple complete OpenStack environments on VMs. Instructions for preparing a devops environment can be found at http://docs.mirantis.com/fuel-dev/devops.html.


There are two types of documentation in Fuel: development and user. Source code of the development documentation can be found at fuel-web repository; users, at fuel-docs repository. Documentation is treated as a source code.

Writing Documentation

Keeping the Documentation up to date is hard and it is a critical part in every project. User Documentation Repository contains the documentation in RST format. Fuel Development Team uses OpenStack DocImpact process to unify and bring the top quality for User Documentation. When patchset should be documented or requires update in Documentation, the Reviewer may gently ask the Commiter to update commit message with 'DocImpact' tag. In this case a new bug will be created which allow the Documentation team to work with the Commiter on Documentation.

Update and expand current documentation

Feel free to file bug if you find a problem with the documentation, and provide with a fix for it via same code contribution policy and procedures. There is building documentation page to help with an environment setup for development documentation.

Release Notes Checklist

New Features

For every blueprint listed on the milestone page in Launchpad (e.g. https://launchpad.net/fuel/+milestone/5.1), find answers to the following questions:

  • What is the visible impact of the change for a user?
  • Was this previously documented as a Known Issue?

If it is a user visible improvement, add a New Features entry about it. Explain when this feature is important, how it can be enabled, and what are the current expectations and limitations.

If it was a Known Issue before, add a Resolved Issues entry.

Resolved Issues

Review all bugs targeted for the current milestone that have "release-notes" tag attached, as well as all Critical and High priority bugs on the milestone page. Sort bugs by Number from highest to lowest, so that you can see when you've reached the bugs that you have already reviewed. If bug status for the current milestone is Fix Committed or Fix Released, consider it for Resolved Issues list. Find answers to:

  • Was this problem present in the previous GA release?
  • How does one confirm if their environment is affected?
  • If you're affected, how do you recover?
  • What was the root cause and what had to be changed to resolve the issue?

Known Issues

Review all bugs targeted at the current milestone with status Won't Fix, and all open (Confirmed, Triaged, or In Progress) bugs in future releases (both feature and maintenance release series). Look for bugs with "release-notes" tag as well as bugs with Critical and High priority. Questions to answer are:

  • How does one confirm if their environment is affected?
  • Is there a workaround?
  • What is the recovery procedure?


Verify bugs

This is very easy to get started, but help here is actually very valuable. Especially when it comes to bugfixes which are relevant to only certain types of hardware. When bugfix is merged, bug is automatically moves to "Fix Committed" status. In Fuel, we set "Fix Released" status for a bug only when it was verified by someone else than a developer. You can simple check out all fix committed bugs and start verifying them. It is required to be in fuel-bugs LP group to be able to change bug status. However you can leave a comment in bug report, and it will be enough for bug supervisors to change bug status. By your request, you can be included into fuel-bugs team to manage bugs yourself.

Test and report bugs

You can always build a developers ISO from master following instructions at http://docs.mirantis.com/fuel-dev/develop/env.html#building-the-fuel-iso. Test different deployment modes, and file bugs. Please do not hesitate to share your findings in IRC for any details you would want to know. Feel free to file bug in a format you want, however it would be great to see a bug in a certain format, with all details in place - to easily reproduce and save a time of developers. You can follow the following simple guidance, which a little bit extend official OpenStack Bugs page.

The bugs you report for Fuel can be either “Public” or “Private”. Private bugs become visible only for Dev, QA, and Support teams. The guidance is as follows:

  • Normally you would want to report a “Public” bug
  • However, if a bug contains any sensitive information, or security leak information, please report a “Private” bug

Here is how you file a bug:

  • Go to https://launchpad.net/fuel
  • Select “Report a bug” on the right
  • Fill in “Summary” field for a bug. It is going to be the headline. Please be descriptive but short and to the point.
    • Bad - "Savanna doesn’t install"
    • Good - "Savanna fails to install in HA mode when “Neutron with VLANs” network is selected"
  • Enter “Further information”. This is a bug description. It should contain the following sections:
    • Description of the environment. Provide enough relevant information:
      • Output of http://fuel-master-node:8000/api/version/
      • Operating System
      • Reference Architecture (HA / non-HA)
      • Network model (Nova-network, Neutron+VLAN, Neutron+GRE, etc.)
      • Related Projects installed (Savanna, Murano, Ceilometer)
    • Steps to reproduce
      • Bad: Run the deployment in HA configuration
      • Good:
        1. Create a new cluster
        2. Select HA mode, “Neutron with VLANs” for network, and choose to install Savanna
        3. Leave defaults the rest of the settings. Run cluster installation
    • Expected result:
      • Good: Savanna is deployed, up and running.
    • Actual result:
      • Bad: Savanna fails to install.
      • Good: Savanna installation fails with the error message “xxx”. Please see the attached screenshot which shows the errors on “Logs” tab.
    • Workaround
      • Bad: Don’t use “Neutron with VLANs”
      • Good: Switch network mode to “Neutron with GRE” for the deployment to complete successfully.
    • Impact
      • Bad: Needs to be fixed.
      • Good: deployment cannot be completed, because customer requires us to implement a use case for Savanna and “Neutron with VLANs”. Changing configuration to “Neutron with GRE” is not as acceptable option here so this has to be addressed as soon as possible.
  • Select visibility for the bug under “This bug contains information that is” field. Either leave it as “Public” (default) or set it to “Private” per the above guidance
  • Add attachments under “Extra Options” section
    • Logs
    • Diagnostic snapshot
    • Screenshots
  • After everything is entered, select the “Submit bug report” button

Confirm and triage bugs

This has nothing different from OpenStack documentation. Please follow Bugs and BugTriage pages.

OpenStack bug priorities converted to Fuel specifics:

  • Critical = can't deploy anything and there's no trivial workaround; data loss; or security vulnerability
  • High = specific hardware, configurations, or components are unusable and there's no workaround; or everything is broken but there's a workaround
  • Medium = specific hardware, configurations, or components are working incorrectly; or is completely unusable but there's a workaround
  • Low = minor feature is broken and can be fixed with a trivial workaround; or a cosmetic defect
  • Wishlist = not a bug, should be either converted to blueprint and closed as Invalid, or closed as Won't Fix

Fix bugs

The most simple and easy way to contribute code into Fuel is to start with bug fixes. First of all, check out bugs with "low-hanging-fruit" tag. You can also take any other bug. For easier management of bugs, Fuel uses multiple functional groups, and you will see bugs assigned to fuel-python, fuel-library, fuel-qa and other teams. Feel free to pick any of those. It is assigned to group, so group can get an email notification about a bug. Unless it is reassigned to particular engineer to work on that bug, then it means the bug is not taken by anyone yet, so feel free to take it. Bugs with assignee set to a person are not yet imply that someone works on them (but it should in ideal world). If it is even in "in progress" state, feel free to ping a person and ask if he really works on that bug, and feel free to assign yourself otherwise.

Please notice, that OpenStack Infra uses strict checks on your git commit messages. The most important rules are:

  • Keep your commit title short (<80 symbols). It must not end with dot.
  • Body of commit message should be separated from title by one empty line
  • If patch closes bug, then it must have in a body "Closes-Bug: #12345", where 12345 is your LP bug number
  • If patch relates to bug, but doesn't completely solve an issue, then you must use "Related-Bug: #12345"

Full guide is available at GitCommitMessages page.

Backport bugfixes to stable release series

When you create a new bug with High or Critical priority or upgrade an existing bug, always check if this bug is present in the supported stable release series (at least one most recent stable release). If it is present there, target it to all affected series (even if you don't expect to be able to eventually backport a fix). If it's not present in stable releases, document that on the bug so that other people don't have to re-check.

When you propose a fix for a bug, always start with fixing it in the master branch. If the fix only applies to the stable branch and is not relevant in master, explain that in the commit message. For a bug targeted for stable release series, cherry-pick the fix commit onto the stable/x.x branch for each series it is targeted for. Use the same Change-Id and topic (git review -t bug/<id>) to make it easier to track down all backports for that bug. You can also use "Cherry Pick To" button in Gerrit if the commit can be applied to the stable branch without conflicts.

When you approve a bugfix commit for master branch, use the information available so far on the bug and in the review request to review and maybe update backporting status of the bug. Is its priority high enough to need a backport? Is it targeted to all affected release series? Are there backport commits already?

  • For all series where backport should exist and doesn't, create a backport review request yourself.
  • For all other affected series, change bug status to Won't Fix and explain in bug comments.
  • Do not merge commits into stable branches until it was merged into master, unless commit message explicitly documents why it doesn't apply to master.


Propose enhancements

Enhancements for Fuel are proposed using the mechanism of blueprints. The process is very similar to the bugs:

  • Select "Register a Blueprint". Typically, you’ll find this link on the right side of the launchpad page.
    • Enter a Name for the blueprint. If possible, include the name of the sub-component of fuel as the first word of the name (or just fuel for a broader blueprint), then a very short descriptor using dashes between words. For example, ui-declarative-wizard or fuel-stop-deployment.
    • Enter a Title for the blueprint. The title should describe the feature as clearly as possible in up to 70 characters. This title is displayed in every feature list or report.
  • Enter a Summary of the blueprint.
    • Summarize the idea of the blueprint in a user story. If you have an existing user story in a public document, include the link.
    • If a public document isn’t yet created and the user story is extensive, you can use https://etherpad.openstack.org/ to document the full user story. You can use the Name that you used for the blueprint as the Pad name.
  • Propose your blueprint by selecting the milestone in which you plan to complete the blueprint.
  • You won’t need to enter any other fields, so now just choose Register Blueprint.

If you’re just entering a new idea without a design, you can leave the specification URL field blank. If you have a design, here is how you get it published and approved:

  • Upload a design specification in the "specs/<release>" folder in fuel-specs
    • e.g. access-control-master-node
    • it should be based on the template, see the instructions in the template for more details
    • get it reviewed by submitting your patch using Gerrit, in the usual way: Gerrit_Workflow
    • at the end of each release, non-completed specs will be removed
    • you need to re-submit for the following release, should the blueprint slip
  • Once your design specification has been approved and merged into fuel-specs git repo:
    • Update your blueprint's specification URL to point to the design specification in fuel-specs git
    • Note, this should link to git (as in the template link above), not to the gerrit change

When done, drop an email about the new blueprint to the mailing list to attract attention of Fuel developers, who are likely to provide early feedback and request additional information.

Please read OpenStack Blueprints page for detailed definition of blueprints and their lifecycle.

Implement new features

To implement a new feature, you will need to address the following:

  1. File a blueprint, with all required feature details, as described in Propose enhancements section above and on Blueprints page
  2. PTL or core developers of Fuel should approve a blueprint, when all required information is provided.
  3. Please no active contribution unless there is an agreement on design. To get an approval, you can discuss a feature in the mailing list.
  4. Every new feature must not break other features, and whether work fine with features we had before, or be disabled in combination with features which do not work with the new one. Short list of features to check compatibility with:
    • All distributions (currently CentOS & Ubuntu)
    • Networking (nova-network, Neutron)
    • Combination with other roles on a node. For example, MongoDB role should not be placed with Ceph.
    • Disk partitioning (will it use existing partition or new one needs to be created?)
    • Network verification
  5. Other requirements for features:
    • logging of services should be done via rsyslog for Fuel Library contributions
    • implementation should be scalable, or otherwise limitations should be clearly stated in a design doc. It is unacceptable to degrade scalability and performance of already existing features.
  6. Start implementation and propose code changes frequently and by small pieces. This is the only way to successful merge - it is unrealistic to review changesets with 1000+ lines of code.
  7. Every feature should have a set of tests:
    • CasperJS and Selenium tests are for Fuel Web UI
    • Nailgun uses Python Unit Test framework for unit and integration tests
    • Astute uses RSpec for unit and integration tests
    • Consider extending OSTF tests for implemented feature
    • System tests, which use Devops framework, are run against an ISO, i.e. when all components are integrated. System tests last for up to 6-8 hours and run every night. As these tests are ran against integrated environment, their result represents a higher interest. Every large feature which has pieces in more than one Fuel component must be covered by system tests.
    • If feature requires special hardware, or special deployment setup, then existing CI should be extended with such hardware and required changes into devops framework. It should be discussed with the Fuel community in mailing list in order to come up with a joint decision.
  8. Documentation. New features must be well documented in both user and development documentation.
  9. Please propose changes for a feature before feature freeze date. Otherwise, changes won't be even reviewed before code freeze, and we will not let changes to land into master before milestone proposed branch is created. This will allow Fuel team to concentrate on stabilization of the current release, and put all the force into squashing bugs. Rules are similar to core OpenStack projects, see FeatureFreeze and ReleaseCycle.


Unit and integration tests for Nailgun

Nailgun uses Python Unit Test framework for unit and integration tests. Help in writing test is highly appreciated - we always want better coverage! Please checkout how to setup development environment for Nailgun tests, and follow How to Test Your Code guidance.

Code review rules

When contributing code changes to Fuel, please use the OpenStack Gerrit workflow and follow Fuel specific rules and recommendations.