Skip to content

Commit 07c3557

Browse files
author
Dean Troyer
committed
Add hacking guideline
After all, it _was_ docday when this was proposed! This is by no means complete but some of this has come up a lot recently. Change-Id: I72300506e1c74077d3f9e6bbabea3b2a25a8e829
1 parent 165121f commit 07c3557

File tree

1 file changed

+153
-0
lines changed

1 file changed

+153
-0
lines changed

‎HACKING.rst‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
Contributing to DevStack
2+
========================
3+
4+
5+
General
6+
-------
7+
8+
DevStack is written in POSIX shell script. This choice was made because
9+
it best illustrates the configuration steps that this implementation takes
10+
on setting up and interacting with OpenStack components. DevStack specifies
11+
BASH and is compatible with Bash 3.
12+
13+
DevStack's official repository is located on GitHub at
14+
https://github.com/openstack-dev/devstack.git. Besides the master branch that
15+
tracks the OpenStack trunk branches a separate branch is maintained for all
16+
OpenStack releases starting with Diablo (stable/diablo).
17+
18+
The primary script in DevStack is ``stack.sh``, which performs the bulk of the
19+
work for DevStack's use cases. There is a subscript ``functions`` that contains
20+
generally useful shell functions and is used by a number of the scripts in
21+
DevStack.
22+
23+
A number of additional scripts can be found in the ``tools`` directory that may
24+
be useful in setting up special-case uses of DevStack. These include: bare metal
25+
deployment, ramdisk deployment and Jenkins integration.
26+
27+
28+
Scripts
29+
-------
30+
31+
DevStack scripts should generally begin by calling ``env(1)`` in the shebang line::
32+
33+
#!/usr/bin/env bash
34+
35+
Sometimes the script needs to know the location of the DevStack install directory.
36+
``TOP_DIR`` should always point there, even if the script itself is located in
37+
a subdirectory::
38+
39+
# Keep track of the current devstack directory.
40+
TOP_DIR=$(cd $(dirname "$0") && pwd)
41+
42+
Many scripts will utilize shared functions from the ``functions`` file. There are
43+
also rc files (``stackrc`` and ``openrc``) that are often included to set the primary
44+
configuration of the user environment::
45+
46+
# Use openrc + stackrc + localrc for settings
47+
pushd $(cd $(dirname "$0")/.. && pwd) >/dev/null
48+
49+
# Import common functions
50+
source ./functions
51+
52+
# Import configuration
53+
source ./openrc
54+
popd >/dev/null
55+
56+
``stack.sh`` is a rather large monolithic script that flows through from beginning
57+
to end. There is a proposal to segment it to put the OpenStack projects
58+
into their own sub-scripts to better document the projects as a unit rather than
59+
have it scattered throughout ``stack.sh``. Someday.
60+
61+
62+
Documentation
63+
-------------
64+
65+
The official DevStack repo on GitHub does not include a gh-pages branch that
66+
GitHub uses to create static web sites. That branch is maintained in the
67+
`CloudBuilders DevStack repo`__ mirror that supports the
68+
http://devstack.org site. This is the primary DevStack
69+
documentation along with the DevStack scripts themselves.
70+
71+
__ repo_
72+
.. _repo: https://github.com/cloudbuilders/devstack
73+
74+
All of the scripts are processed with shocco_ to render them with the comments
75+
as text describing the script below. For this reason we tend to be a little
76+
verbose in the comments _ABOVE_ the code they pertain to. Shocco also supports
77+
Markdown formatting in the comments; use it sparingly. Specifically, ``stack.sh``
78+
uses Markdown headers to divide the script into logical sections.
79+
80+
.. _shocco: http://rtomayko.github.com/shocco/
81+
82+
83+
Exercises
84+
---------
85+
86+
The scripts in the exercises directory are meant to 1) perform basic operational
87+
checks on certain aspects of OpenStack; and b) document the use of the
88+
OpenStack command-line clients.
89+
90+
In addition to the guidelines above, exercise scripts MUST follow the structure
91+
outlined here. ``swift.sh`` is perhaps the clearest example of these guidelines.
92+
These scripts are executed serially by ``exercise.sh`` in testing situations.
93+
94+
* Begin and end with a banner that stands out in a sea of script logs to aid
95+
in debugging failures, particularly in automated testing situations. If the
96+
end banner is not displayed, the script ended prematurely and can be assumed
97+
to have failed.
98+
99+
::
100+
101+
echo "**************************************************"
102+
echo "Begin DevStack Exercise: $0"
103+
echo "**************************************************"
104+
...
105+
set +o xtrace
106+
echo "**************************************************"
107+
echo "End DevStack Exercise: $0"
108+
echo "**************************************************"
109+
110+
* The scripts will generally have the shell ``xtrace`` attribute set to display
111+
the actual commands being executed, and the ``errexit`` attribute set to exit
112+
the script on non-zero exit codes::
113+
114+
# This script exits on an error so that errors don't compound and you see
115+
# only the first error that occured.
116+
set -o errexit
117+
118+
# Print the commands being run so that we can see the command that triggers
119+
# an error. It is also useful for following allowing as the install occurs.
120+
set -o xtrace
121+
122+
* There are a couple of helper functions in the common ``functions`` sub-script
123+
that will check for non-zero exit codes and unset environment variables and
124+
print a message and exit the script. These should be called after most client
125+
commands that are not otherwise checked to short-circuit long timeouts
126+
(instance boot failure, for example)::
127+
128+
swift post $CONTAINER
129+
die_if_error "Failure creating container $CONTAINER"
130+
131+
FLOATING_IP=`euca-allocate-address | cut -f2`
132+
die_if_not_set FLOATING_IP "Failure allocating floating IP"
133+
134+
* The exercise scripts should only use the various OpenStack client binaries to
135+
interact with OpenStack. This specifically excludes any ``*-manage`` tools
136+
as those assume direct access to configuration and databases, as well as direct
137+
database access from the exercise itself.
138+
139+
* If specific configuration needs to be present for the exercise to complete,
140+
it should be staged in ``stack.sh``, or called from ``stack.sh`` (see
141+
``files/keystone_data.sh`` for an example of this).
142+
143+
* The ``OS_*`` environment variables should be the only ones used for all
144+
authentication to OpenStack clients as documented in the CLIAuth_ wiki page.
145+
146+
.. _CLIAuth: http://wiki.openstack.org/CLIAuth
147+
148+
* The exercise MUST clean up after itself if successful. If it is not successful,
149+
it is assumed that state will be left behind; this allows a chance for developers
150+
to look around and attempt to debug the problem. The exercise SHOULD clean up
151+
or graciously handle possible artifacts left over from previous runs if executed
152+
again. It is acceptable to require a reboot or even a re-install of DevStack
153+
to restore a clean test environment.

0 commit comments

Comments
 (0)