<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Contributing Guide — Horizon 2012.2.3 documentation</title>
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/tweaks.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '2012.2.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/jquery.tweet.js"></script>
<link rel="top" title="Horizon 2012.2.3 documentation" href="index.html" />
<link rel="next" title="Horizon’s tests and you" href="testing.html" />
<link rel="prev" title="Customizing Horizon" href="topics/customizing.html" />
</head>
<body>
<div id="header">
<h1 id="logo"><a href="http://www.openstack.org/">OpenStack</a></h1>
<ul id="navigation">
<li><a href="http://www.openstack.org/" title="Go to the Home page" class="link">Home</a></li>
<li><a href="http://www.openstack.org/projects/" title="Go to the OpenStack Projects page">Projects</a></li>
<li><a href="http://www.openstack.org/user-stories/" title="Go to the User Stories page" class="link">User Stories</a></li>
<li><a href="http://www.openstack.org/community/" title="Go to the Community page" class="link">Community</a></li>
<li><a href="http://www.openstack.org/blog/" title="Go to the OpenStack Blog">Blog</a></li>
<li><a href="http://wiki.openstack.org/" title="Go to the OpenStack Wiki">Wiki</a></li>
<li><a href="http://docs.openstack.org/" title="Go to OpenStack Documentation" class="current">Documentation</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="contributing-guide">
<h1>Contributing Guide<a class="headerlink" href="#contributing-guide" title="Permalink to this headline">¶</a></h1>
<p>First and foremost, thank you for wanting to contribute! It’s the only way
open source works!</p>
<p>Before you dive into writing patches, here are some of the basics:</p>
<ul class="simple">
<li>Project page: <a class="reference external" href="http://launchpad.net/horizon">http://launchpad.net/horizon</a></li>
<li>Bug tracker: <a class="reference external" href="https://bugs.launchpad.net/horizon">https://bugs.launchpad.net/horizon</a></li>
<li>Source code: <a class="reference external" href="https://github.com/openstack/horizon">https://github.com/openstack/horizon</a></li>
<li>Code review: <a class="reference external" href="https://review.openstack.org/#q,status:open+project:openstack/horizon,n,z">https://review.openstack.org/#q,status:open+project:openstack/horizon,n,z</a></li>
<li>Jenkins build status: <a class="reference external" href="https://jenkins.openstack.org/view/Horizon/">https://jenkins.openstack.org/view/Horizon/</a></li>
<li>IRC Channel: #openstack-horizon on Freenode.</li>
</ul>
<div class="section" id="making-contributions">
<h2>Making Contributions<a class="headerlink" href="#making-contributions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="getting-started">
<h3>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h3>
<p>We’ll start by assuming you’ve got a working checkout of the repository (if
not then please see the <a class="reference internal" href="quickstart.html"><em>Horizon Quickstart</em></a>).</p>
<p>Second, you’ll need to take care of a couple administrative tasks:</p>
<ol class="arabic simple">
<li>Create an account on Launchpad.</li>
<li>Sign the <a class="reference external" href="http://wiki.openstack.org/CLA">OpenStack Contributor License Agreement</a> and follow the associated
instructions to verify your signature.</li>
<li>Request to join the <a class="reference external" href="https://launchpad.net/~openstack-cla">OpenStack Contributors</a> team on Launchpad.</li>
<li>Join the <a class="reference external" href="https://launchpad.net/~horizon">Horizon Developers</a> team on Launchpad.</li>
<li>Follow the <a class="reference external" href="http://wiki.openstack.org/GerritWorkflow">instructions for setting up git-review</a> in your
development environment.</li>
</ol>
<p>Whew! Got that all that? Okay! You’re good to go.</p>
</div>
<div class="section" id="ways-to-contribute">
<h3>Ways To Contribute<a class="headerlink" href="#ways-to-contribute" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>If those are too big, there are lots of great ways to get involved without
plunging in head-first:</p>
<ul class="simple">
<li>Report bugs, triage new tickets, and review old tickets on
the <a class="reference external" href="https://bugs.launchpad.net/horizon">bug tracker</a>.</li>
<li>Propose ideas for improvements via Launchpad Blueprints, via the
mailing list on the project page, or on IRC.</li>
<li>Write documentation!</li>
<li>Write unit tests for untested code!</li>
</ul>
</div>
<div class="section" id="choosing-issues-to-work-on">
<h3>Choosing Issues To Work On<a class="headerlink" href="#choosing-issues-to-work-on" title="Permalink to this headline">¶</a></h3>
<p>In general, if you want to write code, there are three cases for issues
you might want to work on:</p>
<ol class="arabic simple">
<li>Confirmed bugs</li>
<li>Approved blueprints (features)</li>
<li>New bugs you’ve discovered</li>
</ol>
<p>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.</p>
<p>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.</p>
</div>
<div class="section" id="after-you-write-your-patch">
<h3>After You Write Your Patch<a class="headerlink" href="#after-you-write-your-patch" title="Permalink to this headline">¶</a></h3>
<p>Once you’ve made your changes, there are a few things to do:</p>
<ul class="simple">
<li>Make sure the unit tests pass: <tt class="docutils literal"><span class="pre">./run_tests.sh</span></tt></li>
<li>Make sure PEP8 is clean: <tt class="docutils literal"><span class="pre">./run_tests.sh</span> <span class="pre">--pep8</span></tt></li>
<li>Make sure your code is up-to-date with the latest master: <tt class="docutils literal"><span class="pre">git</span> <span class="pre">pull</span> <span class="pre">--rebase</span></tt></li>
<li>Finally, run <tt class="docutils literal"><span class="pre">git</span> <span class="pre">review</span></tt> to upload your changes to Gerrit for review.</li>
</ul>
<p>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!</p>
</div>
</div>
<div class="section" id="etiquette">
<h2>Etiquette<a class="headerlink" href="#etiquette" title="Permalink to this headline">¶</a></h2>
<p>The community’s guidelines for etiquette are fairly simple:</p>
<ul class="simple">
<li>Treat everyone respectfully and professionally.</li>
<li>If a bug is “in progress” in the bug tracker, don’t start working on it
without contacting the author. Try on IRC, or via the launchpad email
contact link. If you don’t get a response after a reasonable time, then go
ahead. Checking first avoids duplicate work and makes sure nobody’s toes
get stepped on.</li>
<li>If a blueprint is assigned, even if it hasn’t been started, be sure you
contact the assignee before taking it on. These larger issues often have a
history of discussion or specific implementation details that the assignee
may be aware of that you are not.</li>
<li>Please don’t re-open tickets closed by a core developer. If you disagree with
the decision on the ticket, the appropriate solution is to take it up on
IRC or the mailing list.</li>
<li>Give credit where credit is due; if someone helps you substantially with
a piece of code, it’s polite (though not required) to thank them in your
commit message.</li>
</ul>
</div>
<div class="section" id="code-style">
<h2>Code Style<a class="headerlink" href="#code-style" title="Permalink to this headline">¶</a></h2>
<div class="section" id="python">
<h3>Python<a class="headerlink" href="#python" title="Permalink to this headline">¶</a></h3>
<p>We follow <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP8</a> for all our Python code, and use <tt class="docutils literal"><span class="pre">pep8.py</span></tt> (available
via the shortcut <tt class="docutils literal"><span class="pre">./run_tests.sh</span> <span class="pre">--pep8</span></tt>) to validate that our code
meets proper Python style guidelines.</p>
</div>
<div class="section" id="django">
<h3>Django<a class="headerlink" href="#django" title="Permalink to this headline">¶</a></h3>
<p>Additionally, we follow <a class="reference external" href="https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/coding-style/">Django’s style guide</a> for templates, views, and
other miscellany.</p>
</div>
<div class="section" id="javascript">
<h3>JavaScript<a class="headerlink" href="#javascript" title="Permalink to this headline">¶</a></h3>
<p>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 <a class="reference external" href="http://jslint.com/">JSLint</a> to validate some general best practices.</p>
<p>The default options are mostly good, but the following accommodate some
allowances we make:</p>
<ul class="simple">
<li>Set <tt class="docutils literal"><span class="pre">Indentation</span></tt> to <tt class="docutils literal"><span class="pre">2</span></tt>.</li>
<li>Enable the <tt class="docutils literal"><span class="pre">Assume</span> <span class="pre">console,</span> <span class="pre">alert,</span> <span class="pre">...</span></tt> option.</li>
<li>Enable the <tt class="docutils literal"><span class="pre">Assume</span> <span class="pre">a</span> <span class="pre">browser</span></tt> option.</li>
<li>Enable the <tt class="docutils literal"><span class="pre">Tolerate</span> <span class="pre">missing</span> <span class="pre">'use</span> <span class="pre">strict'</span> <span class="pre">pragma</span></tt> option.</li>
<li>Clear the <tt class="docutils literal"><span class="pre">Maximum</span> <span class="pre">number</span> <span class="pre">of</span> <span class="pre">errors</span></tt> field.</li>
<li>Add <tt class="docutils literal"><span class="pre">horizon,$</span></tt> to the <tt class="docutils literal"><span class="pre">Predefined</span></tt> list.</li>
</ul>
</div>
<div class="section" id="css">
<h3>CSS<a class="headerlink" href="#css" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
</div>
<div class="section" id="html">
<h3>HTML<a class="headerlink" href="#html" title="Permalink to this headline">¶</a></h3>
<p>Again, readability is paramount; however be conscientous of how the browser
will handle whitespace when rendering the output. Two spaces is the preferred
indentation style to match all front-end code.</p>
</div>
<div class="section" id="documentation">
<h3>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h3>
<p>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:</p>
<ul class="simple">
<li>Flow paragraphs such that lines wrap at 80 characters or less.</li>
<li>Use proper grammar, spelling, capitalization and punctuation at all times.</li>
<li>Make use of Sphinx’s autodoc feature to document modules, classes
and functions. This keeps the docs close to the source.</li>
<li>Where possible, use Sphinx’s cross-reference syntax (e.g.
<tt class="docutils literal"><span class="pre">:class:`~horizon.foo.Bar`</span></tt>) when referring to other Horizon components.
The better-linked our docs are, the easier they are to use.</li>
</ul>
<p>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.</p>
</div>
<div class="section" id="conventions">
<h3>Conventions<a class="headerlink" href="#conventions" title="Permalink to this headline">¶</a></h3>
<p>Simply by convention, we have a few rules about naming:</p>
<blockquote>
<div><ul class="simple">
<li>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.</li>
<li>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.</li>
</ul>
</div></blockquote>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Contributing Guide</a><ul>
<li><a class="reference internal" href="#making-contributions">Making Contributions</a><ul>
<li><a class="reference internal" href="#getting-started">Getting Started</a></li>
<li><a class="reference internal" href="#ways-to-contribute">Ways To Contribute</a></li>
<li><a class="reference internal" href="#choosing-issues-to-work-on">Choosing Issues To Work On</a></li>
<li><a class="reference internal" href="#after-you-write-your-patch">After You Write Your Patch</a></li>
</ul>
</li>
<li><a class="reference internal" href="#etiquette">Etiquette</a></li>
<li><a class="reference internal" href="#code-style">Code Style</a><ul>
<li><a class="reference internal" href="#python">Python</a></li>
<li><a class="reference internal" href="#django">Django</a></li>
<li><a class="reference internal" href="#javascript">JavaScript</a></li>
<li><a class="reference internal" href="#css">CSS</a></li>
<li><a class="reference internal" href="#html">HTML</a></li>
<li><a class="reference internal" href="#documentation">Documentation</a></li>
<li><a class="reference internal" href="#conventions">Conventions</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="topics/customizing.html"
title="previous chapter">Customizing Horizon</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="testing.html"
title="next chapter">Horizon’s tests and you</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/contributing.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="testing.html" title="Horizon’s tests and you"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="topics/customizing.html" title="Customizing Horizon"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Horizon 2012.2.3 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2012, OpenStack, LLC.
Last updated on Feb 08, 2013.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
