Improve contributor documentation
Fix various errors in the contributor documentation: - Factual mistakes (wrong file locations, etc) - Formatting errors - Typos Change-Id: I4863ca10a532ac74491cfb19f8382e3d5287d2f3
This commit is contained in:
Ana Krivokapic
parent
258e9b4653
commit
d3c91de71a
@ -74,7 +74,7 @@ Development
|
||||
For development, start with the getting started instructions above.
|
||||
Once you have a working virtualenv and all the necessary packages, read on.
|
||||
|
||||
If dependencies are added to either ``horizon`` or ``openstack-dashboard``,
|
||||
If dependencies are added to either ``horizon`` or ``openstack_dashboard``,
|
||||
they should be added to ``requirements.txt``.
|
||||
|
||||
The ``run_tests.sh`` script invokes tests and analyses on both of these
|
||||
|
||||
@ -11,7 +11,10 @@ Before you dive into writing patches, here are some of the basics:
|
||||
* Bug tracker: https://bugs.launchpad.net/horizon
|
||||
* Source code: https://github.com/openstack/horizon
|
||||
* Code review: https://review.openstack.org/#q,status:open+project:openstack/horizon,n,z
|
||||
* Jenkins build status: https://jenkins.openstack.org/view/Horizon/
|
||||
* Continuous integration:
|
||||
|
||||
* Jenkins: https://jenkins.openstack.org
|
||||
* Zuul: http://status.openstack.org/zuul
|
||||
* IRC Channel: #openstack-horizon on Freenode.
|
||||
|
||||
Making Contributions
|
||||
@ -47,12 +50,13 @@ plunging in head-first:
|
||||
|
||||
* Report bugs, triage new tickets, and review old tickets on
|
||||
the `bug tracker`_.
|
||||
* Propose ideas for improvements via Launchpad Blueprints, via the
|
||||
* Propose ideas for improvements via `Launchpad Blueprints`_, via the
|
||||
mailing list on the project page, or on IRC.
|
||||
* Write documentation!
|
||||
* Write unit tests for untested code!
|
||||
|
||||
.. _`bug tracker`: https://bugs.launchpad.net/horizon
|
||||
.. _`Launchpad Blueprints`: https://blueprints.launchpad.net/horizon
|
||||
|
||||
Choosing Issues To Work On
|
||||
--------------------------
|
||||
@ -165,7 +169,7 @@ so as to match both the JavaScript and HTML files.
|
||||
HTML
|
||||
----
|
||||
|
||||
Again, readability is paramount; however be conscientous of how the browser
|
||||
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.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ Horizon Quickstart
|
||||
Setup
|
||||
=====
|
||||
|
||||
To setup an Horizon development environment simply clone the Horizon git
|
||||
To setup a Horizon development environment simply clone the Horizon git
|
||||
repository from http://github.com/openstack/horizon and execute the
|
||||
``run_tests.sh`` script from the root folder (see :doc:`ref/run_tests`)::
|
||||
|
||||
@ -13,7 +13,7 @@ repository from http://github.com/openstack/horizon and execute the
|
||||
> cd horizon
|
||||
> ./run_tests.sh
|
||||
|
||||
Next you will need to setup your Django application config by copying ``openstack_dashboard/local/local_settings.py.example`` to ``openstack_dashboard/local_settings.py``. To do this quickly you can use the following command::
|
||||
Next you will need to setup your Django application config by copying ``openstack_dashboard/local/local_settings.py.example`` to ``openstack_dashboard/local/local_settings.py``. To do this quickly you can use the following command::
|
||||
|
||||
> cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py
|
||||
|
||||
|
||||
@ -18,10 +18,9 @@ you should do is to run ``./run_tests.sh`` from the root of the repository.
|
||||
This will do two things for you:
|
||||
|
||||
#. Set up a virtual environment for both the ``horizon`` module and
|
||||
the ``openstack-dashboard`` project using
|
||||
``openstack-dashboard/tools/install_venv.py``.
|
||||
#. Run the tests for both ``horizon`` and ``openstack-dashboard`` using
|
||||
their respective environments and verify that evreything is working.
|
||||
the ``openstack_dashboard`` project using ``./tools/install_venv.py``.
|
||||
#. Run the tests for both ``horizon`` and ``openstack_dashboard`` using
|
||||
their respective environments and verify that everything is working.
|
||||
|
||||
Setting up the environment the first time can take several minutes, but only
|
||||
needs to be done once. If dependencies are added in the future, updating the
|
||||
@ -80,7 +79,7 @@ dashboards and panels based on basic templates.
|
||||
Dashboards
|
||||
----------
|
||||
|
||||
To create a new dashboard, run the following:
|
||||
To create a new dashboard, run the following::
|
||||
|
||||
./run_tests.sh -m startdash <dash_name>
|
||||
|
||||
@ -90,13 +89,13 @@ module with the basic dashboard code filled in, and various other common
|
||||
|
||||
Available options:
|
||||
|
||||
* --target: the directory in which the dashboard files should be created.
|
||||
* ``--target``: the directory in which the dashboard files should be created.
|
||||
Default: A new directory within the current directory.
|
||||
|
||||
Panels
|
||||
------
|
||||
|
||||
To create a new panel, run the following:
|
||||
To create a new panel, run the following::
|
||||
|
||||
./run_tests -m startpanel <panel_name> --dashboard=<dashboard_path>
|
||||
|
||||
@ -106,9 +105,9 @@ module with the basic panel code filled in, and various other common
|
||||
|
||||
Available options:
|
||||
|
||||
* -d, --dashboard: The dotted python path to your dashboard app (the module
|
||||
* ``-d``, ``--dashboard``: The dotted python path to your dashboard app (the module
|
||||
which containers the ``dashboard.py`` file.).
|
||||
* --target: the directory in which the panel files should be created.
|
||||
* ``--target``: the directory in which the panel files should be created.
|
||||
If the value is ``auto`` the panel will be created as a new directory inside
|
||||
the dashboard module's directory structure. Default: A new directory within
|
||||
the current directory.
|
||||
@ -166,7 +165,7 @@ the root of the repository with ``run_tests.sh`` like so::
|
||||
|
||||
This is effectively just an alias for::
|
||||
|
||||
./openstack-dashboard/tools/with_venv.sh ./openstack-dashboard/dashboard/manage.py runserver
|
||||
./tools/with_venv.sh ./manage.py runserver
|
||||
|
||||
Generating the documentation
|
||||
============================
|
||||
@ -181,11 +180,11 @@ Updating the translation files
|
||||
==============================
|
||||
|
||||
You can update all of the translation files for both the ``horizon`` app and
|
||||
``openstack_dashboard`` project with a single command:
|
||||
``openstack_dashboard`` project with a single command::
|
||||
|
||||
./run_tests.sh --makemessages
|
||||
|
||||
or, more compactly:
|
||||
or, more compactly::
|
||||
|
||||
./run_tests.sh --m
|
||||
|
||||
@ -215,7 +214,7 @@ Environment Backups
|
||||
|
||||
To speed up the process of doing clean checkouts, running continuous
|
||||
integration tests, etc. there are options for backing up the current
|
||||
environment and restoring from a backup.
|
||||
environment and restoring from a backup::
|
||||
|
||||
./run_tests.sh --restore-environment
|
||||
./run_tests.sh --backup-environment
|
||||
|
||||
@ -21,7 +21,7 @@ goals for the Essex release cycle. Massive strides have been made to allow
|
||||
for the addition of new "plug-in" components and customization of OpenStack
|
||||
Dashboard deployments.
|
||||
|
||||
To support this extensability, all the components used to build on Horizon's
|
||||
To support this extensibility, all the components used to build on Horizon's
|
||||
interface are now modular and reusable. Horizon's own dashboards use these
|
||||
components, and they have all been built with third-party developers in mind.
|
||||
Some of the main components are listed below.
|
||||
@ -49,10 +49,10 @@ Tabs and TabGroups
|
||||
|
||||
Another extremely common user-interface element is the use of "tabs" to break
|
||||
down discrete groups of data into manageable chunks. Since these tabs often
|
||||
encompasse vastly different data, may have completely different access
|
||||
encompass vastly different data, may have completely different access
|
||||
restrictions, and may sometimes be better-off being loaded dynamically rather
|
||||
than with the initial page load, Horizon includes tab and tab group classes for
|
||||
constructing these interfaces elegently and with no knowledge of the HTML, CSS
|
||||
constructing these interfaces elegantly and with no knowledge of the HTML, CSS
|
||||
or JavaScript involved.
|
||||
|
||||
Nova Features
|
||||
@ -75,7 +75,7 @@ Support for Nova's features has been greatly improved in Essex:
|
||||
Settings
|
||||
--------
|
||||
|
||||
A new "Settings" area was added that offers several userful functions:
|
||||
A new "Settings" area was added that offers several useful functions:
|
||||
|
||||
* EC2 credentials download.
|
||||
* OpenStack RC file download.
|
||||
@ -145,4 +145,4 @@ Backwards Compatibility
|
||||
The Essex Horizon release is only partially backwards-compatible with Diablo
|
||||
OpenStack components. While it is largely possible to log in and interact, many
|
||||
functions in Nova, Glance and Keystone changed too substantially in Essex to
|
||||
maintain full compatibliity.
|
||||
maintain full compatibility.
|
||||
|
||||
@ -64,7 +64,7 @@ little to no information as to why.
|
||||
|
||||
In Grizzly we have instead chosen to improve this by treating service API
|
||||
401 and 403 errors as slightly less severe than unauthorized access attempts
|
||||
to resitricted areas of Horizon. The reason for this is threefold:
|
||||
to restricted areas of Horizon. The reason for this is threefold:
|
||||
|
||||
#. For a non-malicious user these errors are almost 100% the result of
|
||||
misconfiguration and this makes debugging possible.
|
||||
@ -120,7 +120,7 @@ involved. Moreover, the combined table-plus-form approach the OpenStack
|
||||
Dashboard had taken only made the UX more frustrating for an already difficult
|
||||
area.
|
||||
|
||||
In Grizzly this has all been reworked to be signficantly simpler, and to
|
||||
In Grizzly this has all been reworked to be significantly simpler, and to
|
||||
provide as much contextual help and streamlining as possible.
|
||||
|
||||
Icons!
|
||||
@ -200,7 +200,7 @@ Other Improvements and Fixes
|
||||
|
||||
* Security groups can be added to a running instance.
|
||||
|
||||
* Volume quotas are handled by the appopriate service depending on whether
|
||||
* Volume quotas are handled by the appropriate service depending on whether
|
||||
or not Cinder is enabled.
|
||||
|
||||
* Password confirmation boxes are now validated for matching passwords on
|
||||
|
||||
@ -59,7 +59,7 @@ continues to grow. New features in the Havana release include:
|
||||
|
||||
* Editable default quotas.
|
||||
* The ability for an administrator to reset the password of a server/instance.
|
||||
* Availablity zone support.
|
||||
* Availability zone support.
|
||||
* Improved region support.
|
||||
* Instance resizing.
|
||||
* Improved boot-from-volume support.
|
||||
|
||||
@ -6,7 +6,7 @@ How to run the tests
|
||||
====================
|
||||
|
||||
Because Horizon is composed of both the ``horizon`` app and the
|
||||
``openstack-dashboard`` reference project, there are in fact two sets of unit
|
||||
``openstack_dashboard`` reference project, there are in fact two sets of unit
|
||||
tests. While they can be run individually without problem, there is an easier
|
||||
way:
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ can be overwritten by adding the attribute ``SITE_BRANDING``
|
||||
to ``local_settings.py`` with the value being the desired name.
|
||||
|
||||
The file ``local_settings.py`` can be found at the Horizon directory path of
|
||||
``horizon/openstack-dashboard/local/local_settings.py``.
|
||||
``openstack_dashboard/local/local_settings.py``.
|
||||
|
||||
Changing the Logo
|
||||
=================
|
||||
@ -24,7 +24,7 @@ The OpenStack Logo is pulled in through ``style.css``::
|
||||
background: url(../images/logo.png) top left no-repeat;
|
||||
|
||||
To override the OpenStack Logo image, replace the image at the directory path
|
||||
``horizon/openstack-dashboard/dashboard/static/dashboard/images/logo.png``.
|
||||
``openstack_dashboard/static/dashboard/img/logo.png``.
|
||||
|
||||
The dimensions should be ``width: 108px, height: 121px``.
|
||||
|
||||
@ -162,8 +162,8 @@ Custom Stylesheets
|
||||
==================
|
||||
|
||||
It is possible to define custom stylesheets for your dashboards. Horizon's base
|
||||
template ``horizon/templates/horizon/base.html`` defines multiple blocks that
|
||||
can be overriden.
|
||||
template ``horizon/templates/base.html`` defines multiple blocks that
|
||||
can be overridden.
|
||||
|
||||
To define custom css files that apply only to a specific dashboard, create
|
||||
a base template in your dashboard's templates folder, which extends Horizon's
|
||||
|
||||
@ -147,7 +147,7 @@ Enabled by::
|
||||
SESSION_ENGINE = 'django.core.cache.backends.db.DatabaseCache'
|
||||
DATABASES = {
|
||||
'default': {
|
||||
# Databe configuration here
|
||||
# Database configuration here
|
||||
}
|
||||
}
|
||||
|
||||
@ -201,7 +201,7 @@ When implementing Horizon for public usage, with the website served through
|
||||
HTTPS, it is recommended that the following settings are applied.
|
||||
|
||||
To help protect the session cookies from `cross-site scripting`_, add the
|
||||
following to ``local_settings.py`` :
|
||||
following to ``local_settings.py``::
|
||||
|
||||
CSRF_COOKIE_SECURE = True
|
||||
SESSION_COOKIE_SECURE = True
|
||||
|
||||
@ -45,7 +45,7 @@ the files listed in ``POLICY_FILES`` or all policy checks will pass.
|
||||
``POLICY_FILES``
|
||||
----------------
|
||||
|
||||
Default: { 'identity': 'keystone_policy.json', 'compute': 'nova_policy.json'}
|
||||
Default: ``{'identity': 'keystone_policy.json', 'compute': 'nova_policy.json'}``
|
||||
|
||||
This should essentially be the mapping of the contents of ``POLICY_FILES_PATH``
|
||||
to service types. When policy.json files are added to the directory
|
||||
@ -102,7 +102,7 @@ x tuples can be added to enforce x rules.
|
||||
|
||||
.. note::
|
||||
|
||||
If a rule specified is not found in the policy file. The policy check
|
||||
If a rule specified is not found in the policy file, the policy check
|
||||
will return False and the action will not be allowed.
|
||||
|
||||
The secondary way to add a role based check is to directly use the
|
||||
@ -144,5 +144,5 @@ then access is allowed.
|
||||
When deriving the :class:`horizon.tables.Action` class for use in a table, if
|
||||
a policy check is desired for a particular target, the implementer should
|
||||
override the :meth:`horizon.tables.Action.get_policy_target` method. This
|
||||
allows a programatic way to specify the target based on the current datum. The
|
||||
allows a programmatic way to specify the target based on the current datum. The
|
||||
value returned should be the target dictionary.
|
||||
|
||||
@ -21,8 +21,8 @@ and a few notes on the Django-related settings.
|
||||
|
||||
Prior to the Essex release of Horizon there were settings which controlled
|
||||
whether features such as Object Storage/Swift or Networking/Neutron would be
|
||||
enabled in the OpenStack Dashboard. This code has beenlong-since removed and
|
||||
those pre-Essex settings have no impact now.
|
||||
enabled in the OpenStack Dashboard. This code has long since been removed
|
||||
and those pre-Essex settings have no impact now.
|
||||
|
||||
In Essex and later, the Service Catalog returned by the Identity Service
|
||||
after a user has successfully authenticated determines the dashboards and
|
||||
@ -83,7 +83,7 @@ expressed in milliseconds.
|
||||
``help_url``
|
||||
------------
|
||||
|
||||
Default: None
|
||||
Default: ``None``
|
||||
|
||||
If provided, a "Help" link will be displayed in the site header which links
|
||||
to the value of this settings (ideally a URL containing help information).
|
||||
@ -99,7 +99,7 @@ exception handling should be aware of.
|
||||
``password_validator``
|
||||
----------------------
|
||||
|
||||
Default: {'regex': '.*', 'help_text': _("Password is not accepted")}
|
||||
Default: ``{'regex': '.*', 'help_text': _("Password is not accepted")}``
|
||||
|
||||
A dictionary containing a regular expression which will be used for password
|
||||
validation and help text which will be displayed if the password does not
|
||||
@ -183,7 +183,7 @@ If you do not have multiple regions you should use the ``OPENSTACK_HOST`` and
|
||||
``OPENSTACK_KEYSTONE_DEFAULT_ROLE``
|
||||
-----------------------------------
|
||||
|
||||
Default: "Member"
|
||||
Default: ``"Member"``
|
||||
|
||||
The name of the role which will be assigned to a user when added to a project.
|
||||
This name must correspond to a role name in Keystone.
|
||||
@ -280,7 +280,7 @@ define the policy rules actions are verified against.
|
||||
``POLICY_FILES``
|
||||
----------------
|
||||
|
||||
Default: ``{ 'identity': 'keystone_policy.json', 'compute': 'nova_policy.json'}``
|
||||
Default: ``{'identity': 'keystone_policy.json', 'compute': 'nova_policy.json'}``
|
||||
|
||||
This should essentially be the mapping of the contents of ``POLICY_FILES_PATH``
|
||||
to service types. When policy.json files are added to ``POLICY_FILES_PATH``,
|
||||
@ -289,10 +289,22 @@ they should be included here too.
|
||||
``OPENSTACK_IMAGE_BACKEND``
|
||||
---------------------------
|
||||
|
||||
Default: ``{ 'image_formats': [('', ''), ('aki', _('AKI - Amazon Kernel Image')),
|
||||
('ami', _('AMI - Amazon Machine Image')), ('ari', _('ARI - Amazon Ramdisk Image')),
|
||||
('iso', _('ISO - Optical Disk Image')), ('qcow2', _('QCOW2 - QEMU Emulator')),
|
||||
('raw', _('Raw')), ('vdi', _('VDI')), ('vhd', _('VHD')), ('vmdk', _('VMDK'))] }``
|
||||
Default::
|
||||
|
||||
{
|
||||
'image_formats': [
|
||||
('', ''),
|
||||
('aki', _('AKI - Amazon Kernel Image')),
|
||||
('ami', _('AMI - Amazon Machine Image')),
|
||||
('ari', _('ARI - Amazon Ramdisk Image')),
|
||||
('iso', _('ISO - Optical Disk Image')),
|
||||
('qcow2', _('QCOW2 - QEMU Emulator')),
|
||||
('raw', _('Raw')),
|
||||
('vdi', _('VDI')),
|
||||
('vhd', _('VHD')),
|
||||
('vmdk', _('VMDK'))
|
||||
]
|
||||
}
|
||||
|
||||
Used to customize features related to the image service, such as the list of
|
||||
supported image formats.
|
||||
|
||||
@ -59,7 +59,7 @@ Cons:
|
||||
in terms of inputs and outputs.
|
||||
* Often requires writing a separate set of tests and/or using a different
|
||||
testing framework from your unit tests.
|
||||
* Don't offer any insight into the quality or status of the underlying code,
|
||||
* Doesn't offer any insight into the quality or status of the underlying code,
|
||||
only verifies that it works or it doesn't.
|
||||
|
||||
Integration Tests
|
||||
@ -170,7 +170,7 @@ is tested... these types of things aren't always easy, but they're extremely
|
||||
necessary.
|
||||
|
||||
To that end, Horizon includes several custom assertions to make these tasks
|
||||
easier. :meth:`~horizon.test.helpers.TestCase.assertNoFormErrors`,
|
||||
easier. :meth:`~openstack_dashboard.test.helpers.TestCase.assertNoFormErrors`,
|
||||
:meth:`~horizon.test.helpers.TestCase.assertMessageCount`, and
|
||||
:meth:`~horizon.test.helpers.TestCase.assertNoMessages` all exist for exactly
|
||||
these purposes. Moreover, they provide useful output when things go wrong so
|
||||
@ -185,10 +185,10 @@ Debugging Unit Tests
|
||||
Tips and tricks
|
||||
---------------
|
||||
|
||||
#. Use :meth:`~horizon.test.helpers.TestCase.assertNoFormErrors` immediately
|
||||
after your ``client.post`` call for tests that handle form views. This will
|
||||
immediately fail if your form POST failed due to a validation error and
|
||||
tell you what the error was.
|
||||
#. Use :meth:`~openstack_dashboard.test.helpers.TestCase.assertNoFormErrors`
|
||||
immediately after your ``client.post`` call for tests that handle form views.
|
||||
This will immediately fail if your form POST failed due to a validation error
|
||||
and tell you what the error was.
|
||||
|
||||
#. Use :meth:`~horizon.test.helpers.TestCase.assertMessageCount` and
|
||||
:meth:`~horizon.test.helpers.TestCase.assertNoMessages` when a piece of code
|
||||
@ -270,7 +270,7 @@ Expected Method Never Called
|
||||
This one is the opposite of the unexpected method call. This one means you
|
||||
told mox to expect a call and it didn't happen. This is almost always the
|
||||
result of an error in the conditions of the test. Using the
|
||||
:meth:`~horizon.test.helpers.TestCase.assertNoFormErrors` and
|
||||
:meth:`~openstack_dashboard.test.helpers.TestCase.assertNoFormErrors` and
|
||||
:meth:`~horizon.test.helpers.TestCase.assertMessageCount` will make it readily
|
||||
apparent what the problem is in the majority of cases. If not, then use ``pdb``
|
||||
and start interrupting the code flow to see where things are getting off track.
|
||||
|
||||
@ -159,7 +159,7 @@ Structure
|
||||
A panel is a relatively flat structure with the exception that templates
|
||||
for a panel in a dashboard live in the dashboard's ``templates`` directory
|
||||
rather than in the panel's ``templates`` directory. Continuing our
|
||||
vizulaization/flocking example, let's see what the looks like::
|
||||
visualization/flocking example, let's see what the file structure looks like::
|
||||
|
||||
# stand-alone panel structure
|
||||
flocking/
|
||||
@ -281,7 +281,7 @@ make everything translatable, we give each column a ``verbose_name`` that's
|
||||
marked for translation.
|
||||
|
||||
Lastly, we added a ``Meta`` class which defines some properties about our
|
||||
table, notably it's (translatable) verbose name, and a semi-unique "slug"-like
|
||||
table, notably its (translatable) verbose name, and a semi-unique "slug"-like
|
||||
name to identify it.
|
||||
|
||||
.. note::
|
||||
@ -311,7 +311,7 @@ First off, let's make a tab for our visualization::
|
||||
return None
|
||||
|
||||
This is about as simple as you can get. Since our visualization will
|
||||
ultiimately use AJAX to load it's data we don't need to pass any context
|
||||
ultimately use AJAX to load it's data we don't need to pass any context
|
||||
to the template, and all we need to define is the name and which template
|
||||
it should use.
|
||||
|
||||
@ -458,12 +458,12 @@ A site built on Horizon takes the form of a very typical Django project::
|
||||
|--static/
|
||||
|
||||
The key bits here are that ``demo_dashboard`` is on our python path, and that
|
||||
the `settings.py`` file here will contain our customized Horizon config.
|
||||
the ``settings.py`` file here will contain our customized Horizon config.
|
||||
|
||||
The settings file
|
||||
-----------------
|
||||
|
||||
There are several key things you will generally want to customiz in your
|
||||
There are several key things you will generally want to customize in your
|
||||
site's settings file: specifying custom dashboards and panels, catching your
|
||||
client's exception classes, and (possibly) specifying a file for advanced
|
||||
overrides.
|
||||
@ -521,7 +521,7 @@ routines for the entire site. By specifying an override file you can alter
|
||||
any behavior you like in existing code. This tutorial won't go in-depth,
|
||||
but let's just say that with great power comes great responsibility.
|
||||
|
||||
To specify am override file, you set the ``'customization_module'`` value in
|
||||
To specify an override file, you set the ``'customization_module'`` value in
|
||||
the ``HORIZON_CONFIG`` dictionary to the dotted python path of your
|
||||
override module::
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user