Move contributing into HACKING
contributing.rst doesn't add very much over the extant HACKING.rst, so move some of the unique bits into HACKING.rst and then link that into the documentation. Change-Id: I0530f38eda92f8dd374c0ec224556ace6e679f54
This commit is contained in:
Ian Wienand
54
HACKING.rst
54
HACKING.rst
@@ -25,23 +25,63 @@ __ contribute_
|
||||
__ lp_
|
||||
.. _lp: https://launchpad.net/~devstack
|
||||
|
||||
The `Gerrit review
|
||||
queue <https://review.openstack.org/#/q/project:openstack-dev/devstack,n,z>`__
|
||||
is used for all commits.
|
||||
|
||||
The primary script in DevStack is ``stack.sh``, which performs the bulk of the
|
||||
work for DevStack's use cases. There is a subscript ``functions`` that contains
|
||||
generally useful shell functions and is used by a number of the scripts in
|
||||
DevStack.
|
||||
|
||||
The ``lib`` directory contains sub-scripts for projects or packages that ``stack.sh``
|
||||
sources to perform much of the work related to those projects. These sub-scripts
|
||||
contain configuration defaults and functions to configure, start and stop the project
|
||||
or package. These variables and functions are also used by related projects,
|
||||
such as Grenade, to manage a DevStack installation.
|
||||
|
||||
A number of additional scripts can be found in the ``tools`` directory that may
|
||||
be useful in supporting DevStack installations. Of particular note are ``info.sh``
|
||||
to collect and report information about the installed system, and ``install_prereqs.sh``
|
||||
that handles installation of the prerequisite packages for DevStack. It is
|
||||
suitable, for example, to pre-load a system for making a snapshot.
|
||||
|
||||
Repo Layout
|
||||
-----------
|
||||
|
||||
The DevStack repo generally keeps all of the primary scripts at the root
|
||||
level.
|
||||
|
||||
``doc`` - Contains the Sphinx source for the documentation.
|
||||
``tools/build_docs.sh`` is used to generate the HTML versions of the
|
||||
DevStack scripts. A complete doc build can be run with ``tox -edocs``.
|
||||
|
||||
``exercises`` - Contains the test scripts used to sanity-check and
|
||||
demonstrate some OpenStack functions. These scripts know how to exit
|
||||
early or skip services that are not enabled.
|
||||
|
||||
``extras.d`` - Contains the dispatch scripts called by the hooks in
|
||||
``stack.sh``, ``unstack.sh`` and ``clean.sh``. See :doc:`the plugins
|
||||
docs <plugins>` for more information.
|
||||
|
||||
``files`` - Contains a variety of otherwise lost files used in
|
||||
configuring and operating DevStack. This includes templates for
|
||||
configuration files and the system dependency information. This is also
|
||||
where image files are downloaded and expanded if necessary.
|
||||
|
||||
``lib`` - Contains the sub-scripts specific to each project. This is
|
||||
where the work of managing a project's services is located. Each
|
||||
top-level project (Keystone, Nova, etc) has a file here. Additionally
|
||||
there are some for system services and project plugins. These
|
||||
variables and functions are also used by related projects, such as
|
||||
Grenade, to manage a DevStack installation.
|
||||
|
||||
``samples`` - Contains a sample of the local files not included in the
|
||||
DevStack repo.
|
||||
|
||||
``tests`` - the DevStack test suite is rather sparse, mostly consisting
|
||||
of test of specific fragile functions in the ``functions`` and
|
||||
``functions-common`` files.
|
||||
|
||||
``tools`` - Contains a collection of stand-alone scripts. While these
|
||||
may reference the top-level DevStack configuration they can generally be
|
||||
run alone. There are also some sub-directories to support specific
|
||||
environments such as XenServer.
|
||||
|
||||
|
||||
Scripts
|
||||
-------
|
||||
@@ -249,6 +289,7 @@ Whitespace Rules
|
||||
|
||||
Control Structure Rules
|
||||
-----------------------
|
||||
|
||||
- then should be on the same line as the if
|
||||
- do should be on the same line as the for
|
||||
|
||||
@@ -270,6 +311,7 @@ Example::
|
||||
|
||||
Variables and Functions
|
||||
-----------------------
|
||||
|
||||
- functions should be used whenever possible for clarity
|
||||
- functions should use ``local`` variables as much as possible to
|
||||
ensure they are isolated from the rest of the environment
|
||||
|
||||
@@ -1,94 +0,0 @@
|
||||
============
|
||||
Contributing
|
||||
============
|
||||
|
||||
DevStack uses the standard OpenStack contribution process as outlined in
|
||||
`the OpenStack developer
|
||||
guide <http://docs.openstack.org/infra/manual/developers.html>`__. This
|
||||
means that you will need to meet the requirements of the Contribututors
|
||||
License Agreement (CLA). If you have already done that for another
|
||||
OpenStack project you are good to go.
|
||||
|
||||
Things To Know
|
||||
==============
|
||||
|
||||
|
|
||||
| **Where Things Are**
|
||||
|
||||
The official DevStack repository is located at
|
||||
``git://git.openstack.org/openstack-dev/devstack.git``, replicated from
|
||||
the repo maintained by Gerrit. GitHub also has a mirror at
|
||||
``git://github.com/openstack-dev/devstack.git``.
|
||||
|
||||
The `blueprint <https://blueprints.launchpad.net/devstack>`__ and `bug
|
||||
trackers <https://bugs.launchpad.net/devstack>`__ are on Launchpad. It
|
||||
should be noted that DevStack generally does not use these as strongly
|
||||
as other projects, but we're trying to change that.
|
||||
|
||||
The `Gerrit review
|
||||
queue <https://review.openstack.org/#/q/project:openstack-dev/devstack,n,z>`__
|
||||
is, however, used for all commits except for the text of this website.
|
||||
That should also change in the near future.
|
||||
|
||||
|
|
||||
| **HACKING.rst**
|
||||
|
||||
Like most OpenStack projects, DevStack includes a ``HACKING.rst`` file
|
||||
that describes the layout, style and conventions of the project. Because
|
||||
``HACKING.rst`` is in the main DevStack repo it is considered
|
||||
authoritative. Much of the content on this page is taken from there.
|
||||
|
||||
|
|
||||
| **bashate Formatting**
|
||||
|
||||
Around the time of the OpenStack Havana release we added a tool to do
|
||||
style checking in DevStack similar to what pep8/flake8 do for Python
|
||||
projects. It is still \_very\_ simplistic, focusing mostly on stray
|
||||
whitespace to help prevent -1 on reviews that are otherwise acceptable.
|
||||
Oddly enough it is called ``bashate``. It will be expanded to enforce
|
||||
some of the documentation rules in comments that are used in formatting
|
||||
the script pages for devstack.org and possibly even simple code
|
||||
formatting. Run it on the entire project with ``./run_tests.sh``.
|
||||
|
||||
Code
|
||||
====
|
||||
|
||||
|
|
||||
| **Repo Layout**
|
||||
|
||||
The DevStack repo generally keeps all of the primary scripts at the root
|
||||
level.
|
||||
|
||||
``doc`` - Contains the Sphinx source for the documentation.
|
||||
``tools/build_docs.sh`` is used to generate the HTML versions of the
|
||||
DevStack scripts. A complete doc build can be run with ``tox -edocs``.
|
||||
|
||||
``exercises`` - Contains the test scripts used to sanity-check and
|
||||
demonstrate some OpenStack functions. These scripts know how to exit
|
||||
early or skip services that are not enabled.
|
||||
|
||||
``extras.d`` - Contains the dispatch scripts called by the hooks in
|
||||
``stack.sh``, ``unstack.sh`` and ``clean.sh``. See :doc:`the plugins
|
||||
docs <plugins>` for more information.
|
||||
|
||||
``files`` - Contains a variety of otherwise lost files used in
|
||||
configuring and operating DevStack. This includes templates for
|
||||
configuration files and the system dependency information. This is also
|
||||
where image files are downloaded and expanded if necessary.
|
||||
|
||||
``lib`` - Contains the sub-scripts specific to each project. This is
|
||||
where the work of managing a project's services is located. Each
|
||||
top-level project (Keystone, Nova, etc) has a file here. Additionally
|
||||
there are some for system services and project plugins.
|
||||
|
||||
``samples`` - Contains a sample of the local files not included in the
|
||||
DevStack repo.
|
||||
|
||||
``tests`` - the DevStack test suite is rather sparse, mostly consisting
|
||||
of test of specific fragile functions in the ``functions`` and
|
||||
``functions-common`` files.
|
||||
|
||||
``tools`` - Contains a collection of stand-alone scripts. While these
|
||||
may reference the top-level DevStack configuration they can generally be
|
||||
run alone. There are also some sub-directories to support specific
|
||||
environments such as XenServer.
|
||||
1
doc/source/hacking.rst
Normal file
1
doc/source/hacking.rst
Normal file
@@ -0,0 +1 @@
|
||||
.. include:: ../../HACKING.rst
|
||||
@@ -12,7 +12,7 @@ DevStack - an OpenStack Community Production
|
||||
plugins
|
||||
faq
|
||||
changes
|
||||
contributing
|
||||
hacking
|
||||
|
||||
Quick Start
|
||||
-----------
|
||||
@@ -139,7 +139,7 @@ FAQ
|
||||
Contributing
|
||||
------------
|
||||
|
||||
:doc:`Pitching in to make DevStack a better place <contributing>`
|
||||
:doc:`Pitching in to make DevStack a better place <hacking>`
|
||||
|
||||
Code
|
||||
====
|
||||
|
||||
Reference in New Issue
Block a user