1. devstack
  2. Commit 07c3557383a02b630c7dee720495b65f41410bac
Browse code

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

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