First and foremost, thank you for wanting to contribute! It’s the only way open source works!
Before you dive into writing patches, here are some of the basics:
We’ll start by assuming you’ve got a working checkout of the repository (if not then please see the Horizon Quickstart).
Second, you’ll need to take care of a couple administrative tasks:
Whew! Got that all that? Okay! You’re good to go.
The easiest way to get started with Horizon’s code is to pick a bug on Launchpad that interests you, and start working on that. Alternatively, if there’s an OpenStack API feature you would like to see implemented in Horizon feel free to try building it.
If those are too big, there are lots of great ways to get involved without plunging in head-first:
In general, if you want to write code, there are three cases for issues you might want to work on:
If you have an idea for a new feature that isn’t in a blueprint yet, it’s a good idea to write the blueprint first so you don’t end up writing a bunch of code that may not go in the direction the community wants.
For bugs, open the bug first, but if you can reproduce the bug reliably and identify its cause then it’s usually safe to start working on it. However, getting independent confirmation (and verifying that it’s not a duplicate) is always a good idea if you can be patient.
Once you’ve made your changes, there are a few things to do:
The Horizon core developers will be notified of the new review and will examine it in a timely fashion, either offering feedback or approving it to be merged. If the review is approved, it is sent to Jenkins to verify the unit tests pass and it can be merged cleanly. Once Jenkins approves it, the change will be merged to the master repository and it’s time to celebrate!
The community’s guidelines for etiquette are fairly simple:
We follow PEP8 for all our Python code, and use pep8.py (available via the shortcut ./run_tests.sh --pep8) to validate that our code meets proper Python style guidelines.
Additionally, we follow Django’s style guide for templates, views, and other miscellany.
As a project, Horizon adheres to code quality standards for our JavaScript just as we do for our Python. To that end we recommend (but do not strictly enforce) the use of JSLint to validate some general best practices.
The default options are mostly good, but the following accommodate some allowances we make:
We don’t require that everything works with JavaScript disabled. It’s fine to introduce features that require that JavaScript is enabled in the user’s web browser.
The code has to work on the stable and latest versions of Firefox, Chrome, Safari, and Opera web browsers, and on Microsoft Internet Explorer 9 and later.
Style guidelines for CSS are currently quite minimal. Do your best to make the code readable and well-organized. Two spaces are preferred for indentation so as to match both the JavaScript and HTML files.
We do not bundle the third-party code within Horizon’s source tree anymore, any code that is still there is just left over and will be cleaned up and packaged properly eventually. What we do instead, is packaging the required files as XStatic Python packages and adding them as dependencies to Horizon. In particular, when you need to add a new third-party JavaScript or CSS library to Horizon, follow those steps:
- Check if the library is already packaged as Xstatic on PyPi, by searching for the library name. If it already is, go to step 5. If it is, but not in the right version, contact the original packager.
- Package the library as an Xstatic package by following the instructions in Xstatic documentation.
- Register and upload your library to PyPi. Add “openstackci” user as an owner of that package. Don’t forget to tag your release in the repository.
- Create a new repository on StackForge. Use “xstatic-core” and “xstatic-ptl” groups for the ACLs.
- Add the package to global-requirements. Make sure to mention the license.
- Add the package to Horizon’s requirements.txt file, to its settings.py, and to the _scripts.html or _stylesheets.html templates. Make sure to keep the order alphabetic.
Again, readability is paramount; however be conscientious of how the browser will handle whitespace when rendering the output. Two spaces is the preferred indentation style to match all front-end code.
Horizon’s documentation is written in reStructuredText and uses Sphinx for additional parsing and functionality, and should follow standard practices for writing reST. This includes:
Be sure to generate the documentation before submitting a patch for review. Unexpected warnings often appear when building the documentation, and slight reST syntax errors frequently cause links or cross-references not to work correctly.
Simply by convention, we have a few rules about naming:
- The term “project” is used in place of Keystone’s “tenant” terminology in all user-facing text. The term “tenant” is still used in API code to make things more obvious for developers.
- The term “dashboard” refers to a top-level dashboard class, and “panel” to the sub-items within a dashboard. Referring to a panel as a dashboard is both confusing and incorrect.