Difference between revisions of "Fuel/How to contribute"

Revision as of 23:22, 2 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.

Bugs verification

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

Bugs confirmation and triaging

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

Suggest enhancements

Enhancements should be proposed using the mechanism of blueprints. The process is very similar to the bugs.

• Select Register a Blueprint. Typically, you’ll find this 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 each word. For example:
    • ui-declarative-wizard
    • 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.
• In the Specification URL, enter a URL to an externally available document that contains the design document.
  • If one does not already exist, you can create a new one. Please use Fuel Design Template Document.
  • If you’re just entering a new idea without a design, then you can leave this field blank.
• 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.
• You won’t need to enter any other fields, so now just choose Register Blueprint.
• Drop an email to the mailing list, that you've just registered blueprint - to attract an attention of developers, who are likely to provide early feedback and request additional information.

Please read OpenStack Blueprints page for full description of blueprints, and its lifecycle management.

Documentation

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

Bug fixes

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.

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 at Suggest 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.