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 Quickstart).
Second, you’ll need to take care of a couple administrative tasks:
Whew! Got 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:
Horizon gets translated into multiple languages. The pseudo translation tool can be used to verify that code is ready to be translated. The pseudo tool replaces a language’s translation with a complete, fake translation. Then you can verify that your code properly displays fake translations to validate that your code is ready for translation.
It should look weird. More specifically, the translatable segments are going to start and end with a bracket and they are going to have some added characters. For example, “Log In” will become “[~Log In~您好яшçあ]” This is useful because you can inspect for the following, and consider if your code is working like it should:
Don’t forget to cleanup any pseudo translated po files. Those don’t get merged!
As a project, Horizon adheres to code quality standards.
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.
The following standards are divided into required and recommended sections. Our main goal in establishing these best practices is to have code that is reliable, readable, and maintainable.
Reliable
Note
If typecasting is desired, explicit casting is preferred to keep the meaning of your code clear.
Keep document reflows to a minimum. DOM manipulation is expensive, and can become a performance issue. If you are accessing the DOM, make sure that you are doing it in the most optimized way. One example is to build up a document fragment and then append the fragment to the DOM in one pass instead of doing multiple smaller DOM updates.
Use “strict”, enclosing each JavaScript file inside a self-executing function. The self-executing function keeps the strict scoped to the file, so its variables and methods are not exposed to other JavaScript files in the product.
Note
Using strict will throw exceptions for common coding errors, like accessing global vars, that normally are not flagged.
Example:
(function(){
'use strict';
// code...
})();
Use forEach | each when looping whenever possible. AngularJS, and jQuery both provide for each loops that provide both iteration and scope.
AngularJS:
angular.forEach(objectToIterateOver, function(value, key) {
// loop logic
});
jQuery:
$.each(objectToIterateOver, function( key, value ) {
// loop logic
});
Do not put variables or functions in the global namespace. There are several reasons why globals are bad, one being that all JavaScript included in an application runs in the same scope. The issue with that is if another script has the same method or variable names they overwrite each other.
Always put var in front of your variables. Not putting var in front of a variable puts that variable into the global space, see above.
Do not use eval( ). The eval (expression) evaluates the expression passed to it. This can open up your code to security vulnerabilities and other issues.
Do not use ‘with object {code}’. The with statement is used to access properties of an object. The issue with with is that its execution is not consistent, so by reading the statement in the code it is not always clear how it is being used.
Readable & Maintainable
Give meaningful names to methods and variables.
Avoid excessive nesting.
Avoid HTML and CSS in JS code. HTML and CSS belong in templates and stylesheets respectively. For example:
In our HTML files, we should focus on layout.
In our JS files, we should focus on logic rather than attempting to manipulate/style elements.
<div class="something"></div> $(".something").html("Don't find me this way!");Is better found like:
<div data-something></div> $("div[data-something]").html("You found me correctly!");
Avoid commented-out code.
Avoid dead code.
Performance
Avoid creating instances of the same object repeatedly within the same scope. Instead, assign the object to a variable and re-use the existing object. For example:
$(document).on('click', function() { /* do something. */ });
$(document).on('mouseover', function() { /* do something. */ });
A better approach:
var $document = $(document);
$document.on('click', function() { /* do something. */ });
$document.on('mouseover', function() { /* do something. */ });
In the first approach a jQuery object for document is created each time. The second approach creates only one jQuery object and reuses it. Each object needs to be created, uses memory, and needs to be garbage collected.
Readable & Maintainable
Put a comment at the top of every file explaining what the purpose of this file is when the naming is not obvious. This guideline also applies to methods and variables.
Source-code formatting – (or “beautification”) is recommended but should be used with caution. Keep in mind that if you reformat an entire file that was not previously formatted the same way, it will mess up the diff during the code review. It is best to use a formatter when you are working on a new file by yourself, or with others who are using the same formatter. You can also choose to format a selected portion of a file only. Instructions for setting up JSHint for Eclipse, Sublime Text, Notepad++ and WebStorm/PyCharm are provided.
Use 2 spaces for code indentation.
Use { } for if, for, while statements, and don’t combine them on one line.
// Do this //Not this // Not this
if(x) { if(x) if(x) y =x;
y=x; y=x;
}
Use JSHint in your development environment.
The following standards are divided into required and recommended sections.
Organization: Define your Angular app under the root Angular folder (such as horizon/static/horizon/js/angular/hz.table.js). If your application is small enough you can choose to lump your Controllers, Directives, Filters, etc.. all in the one file. But if you find your file is growing too large and readability is becoming an issue, consider moving functionality into their own files under sub folders as described in the Recommended section.
Separate presentation and business logic. Controllers are for business logic, and directives for presentation.
Scope is not the model (model is your JavaScript Objects). The scope references the model.
Since Django already uses {{ }}, use {$ $} or {% verbatim %} instead.
For localization in JavaScript files use either gettext or ngettext. Only those two methods are recognized by our tools and will be included in the .po file after running ./run_tests --makemessages.
// recognized
gettext("translatable text");
ngettext("translatable text");
// not recognized
var _ = gettext;
_('translatable text');
$window.gettext('translatable text');
For localization of AngularJS templates in Horizon, there are a couple of ways to do it.
Use these directories: filters, directives, controllers, and templates.
Note
When you use the directory name, the file name does not have to include words like “directive” or “filter”.
Put “Ctrl” on the end of a controller file name.
Don’t use variables like “app” that are at the highest level in the file, when Angular gives an alternative. For example use function chaining:
angular.module('my_module')
.controller('my_controller', ['$scope', function($scope) {
// controller code
}]).service('my_service', ['$scope', function($scope) {
// service code
}]);
JSHint is a great tool to be used during your code editing to improve JavaScript quality by checking your code against a configurable list of checks. Therefore, JavaScript developers should configure their editors to use JSHint to warn them of any such errors so they can be addressed. Since JSHint has a ton of configuration options to choose from, links are provided below to the options Horizon wants enforced along with the instructions for setting up JSHint for Eclipse, Sublime Text, Notepad++ and WebStorm/PyCharm.
JSHint configuration file: .jshintrc
Instructions for setting up JSHint: JSHint setup instructions
Note
JSHint is part of the automated unit tests performed by Jenkins. The automated test use the default configurations, which are less strict than the configurations we recommended to run in your local development environment.
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.
- Create a new repository on StackForge. Use “xstatic-core” and “xstatic-ptl” groups for the ACLs. Make sure to include the publish-to-pypi job.
- Setup PyPi to allow OpenStack to publish your package.
- Tag your release. That will cause it to be automatically packaged and released to PyPi.
- 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.
Warning
Note that once a package is released, you can not “unrealease” it. You should never attempt to modify, delete or rename a released package without a lot of careful planning and feedback from all projects that use it.
For the purpose of fixing packaging mistakes, XStatic has the build number mechanism. Simply fix the error, increment the build number and release the newer package.
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.