Difference between revisions of "Fuel/How to contribute"

Revision as of 00:32, 28 June 2014

Overview

Fuel is large project which intersect Programming, Linux and Networking. It is written in Python, Ruby and JavaScript. It also has a number of build scripts in bash & make. Documentation is written in Sphinx. We are welcome you to contribute in any area of the above or beyond.

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 configurations or components are unusable and there's no workaround; or everything is broken but there's a workaround
Medium = specific configuration or component is 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

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.

Update and expand documentation

There are two types of documentation in Fuel: development and user. Source code of the development documentation can be found in fuel-web repository; users, at fuel-docs repository. Documentation is treated as source code: feel free to file bug if you find a problem with the docs, and provide a fix for it via same code contribution policy and procedures. There is building documentation page to help with an environment setup for development docs.

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, cherry-pick the fix commit onto the stable/x.x branch for each series it is targeted to. 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
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.

Implement new features

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

File a blueprint, with all required feature details, as described in Propose enhancements section above and on Blueprints page
PTL or core developers of Fuel should approve a blueprint, when all required information is provided.
Please no active contribution unless there is an agreement on design. To get an approval, you can discuss a feature in the mailing list.
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
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.
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.
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.
Documentation. New features must be well documented in both user and development documentation.
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.

@@ Line 51: / Line 51: @@
 == 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 configurations or components are unusable and there's no workaround; or everything is broken but there's a workaround
+* Medium = specific configuration or component is 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
 == Propose enhancements ==