1. devstack
  2. Commit bd6614a8e0040690aca5121cdf08a7ee17fe7984
Browse code

Add development page with devstack

It turns out we never really had a document on how to work with
devstack in the devstack docs. At one point this was just cultural
knowledge passed down, but with the size of our community, we can't
rely on that any more.

Change-Id: I28f896ea507ccbba5164ebfc5415d22207f52e98

Sean Dague authored on 2016/08/11 22:05:16
Showing 4 changed files
doc/source/assets/images/screen_session_1.png
History View file @ bd6614a
1 1 
new file mode 100644
2 2 
Binary files /dev/null and b/doc/source/assets/images/screen_session_1.png differ
doc/source/development.rst
History View file @ bd6614a
3 3 
new file mode 100644
... ... 
@@ -0,0 +1,140 @@
0 
+==========================
1 
+ Developing with Devstack
2 
+==========================
3 
+
4 
+Now that you have your nifty DevStack up and running, what can you do
5 
+with it?
6 
+
7 
+Inspecting Services
8 
+===================
9 
+
10 
+By default most services in DevStack are running in a `screen
11 
+<https://www.gnu.org/software/screen/manual/screen.html>`_
12 
+session.
13 
+
14 
+.. code-block:: bash
15 
+
16 
+   os3:~> screen -list
17 
+   There is a screen on:
18 
+        28994.stack	(08/10/2016 09:01:33 PM)	(Detached)
19 
+   1 Socket in /var/run/screen/S-sdague.
20 
+
21 
+You can attach to this screen session using ``screen -r`` which gives
22 
+you a view of the services in action.
23 
+
24 
+.. image:: assets/images/screen_session_1.png
25 
+   :width: 100%
26 
+
27 
+Basic Screen Commands
28 
+---------------------
29 
+
30 
+The following minimal commands will be useful to using screen:
31 
+
32 
+* ``ctrl-a n`` - go to next window. Next is assumed to be right of
33 
+  current window.
34 
+* ``ctrl-a p`` - go to previous window. Previous is assumed to be left
35 
+  of current window.
36 
+* ``ctrl-a [`` - entry copy/scrollback mode. This allows you to
37 
+  navigate back through the logs with the up arrow.
38 
+* ``ctrl-a d`` - detach from screen. Gets you back to a normal
39 
+  terminal, while leaving everything running.
40 
+
41 
+For more about using screen, see the excellent `screen manual
42 
+<https://www.gnu.org/software/screen/manual/screen.html>`_.
43 
+
44 
+Patching a Service
45 
+==================
46 
+
47 
+If you want to make a quick change to a running service the easiest
48 
+way to do this is:
49 
+
50 
+* attach to screen
51 
+* navigate to the window in question
52 
+* ``ctrl-c`` to kill the service
53 
+* make appropriate changes to the code
54 
+* ``up arrow`` in the screen window to display the command used to run
55 
+  that service
56 
+* ``enter`` to restart the service
57 
+
58 
+This works for services, except those running under Apache (currently
59 
+just ``keystone`` by default).
60 
+
61 
+.. warning::
62 
+
63 
+   All changes you are making are in checked out git trees that
64 
+   DevStack thinks it has full control over. Uncommitted work, or
65 
+   work committed to the master branch, may be overwritten during
66 
+   subsequent DevStack runs.
67 
+
68 
+Testing a Patch Series
69 
+======================
70 
+
71 
+When testing a larger set of patches, or patches that will impact more
72 
+than one service within a project, it is often less confusing to use
73 
+custom git locations, and make all your changes in a dedicated git
74 
+tree.
75 
+
76 
+In your ``local.conf`` you can add ``**_REPO``, ``**_BRANCH`` for most projects
77 
+to use a custom git tree instead of the default upstream ones.
78 
+
79 
+For instance:
80 
+
81 
+.. code-block:: bash
82 
+
83 
+   [[local|localrc]]
84 
+   NOVA_REPO=/home/sdague/nova
85 
+   NOVA_BRANCH=fold_disk_config
86 
+
87 
+Will use a custom git tree and branch when doing any devstack
88 
+operations, such as ``stack.sh``.
89 
+
90 
+When testing complicated changes committing to these trees, then doing
91 
+``./unstack.sh && ./stack.sh`` is often a valuable way to
92 
+iterate. This does take longer per iteration than direct patching, as
93 
+the whole devstack needs to rebuild.
94 
+
95 
+You can use this same approach to test patches that are up for review
96 
+in gerrit by using the ref name that gerrit assigns to each change.
97 
+
98 
+.. code-block:: bash
99 
+
100 
+   [[local|localrc]]
101 
+   NOVA_BRANCH=refs/changes/10/353710/1
102 
+
103 
+
104 
+Testing Changes to Apache Based Services
105 
+========================================
106 
+
107 
+When testing changes to Apache based services, such as ``keystone``,
108 
+you can either use the Testing a Patch Series approach above, or make
109 
+changes in the code tree and issue an apache restart.
110 
+
111 
+
112 
+Testing Changes to Libraries
113 
+============================
114 
+
115 
+When testing changes to libraries consumed by OpenStack services (such
116 
+as oslo or any of the python-fooclient libraries) things are a little
117 
+more complicated. By default we only test with released versions of
118 
+these libraries that are on pypi.
119 
+
120 
+You must first override this with the setting ``LIBS_FROM_GIT``. This
121 
+will enable your DevStack with the git version of that library instead
122 
+of the released version.
123 
+
124 
+After that point you can also specify ``**_REPO``, ``**_BRANCH`` to use
125 
+your changes instead of just upstream master.
126 
+
127 
+.. code-block:: bash
128 
+
129 
+   [[local|localrc]]
130 
+   LIBS_FROM_GIT=oslo.policy
131 
+   OSLOPOLICY_REPO=/home/sdague/oslo.policy
132 
+   OSLOPOLICY_BRANCH=better_exception
133 
+
134 
+Because libraries are used by many services, library changes really
135 
+need to go through a full ``./unstack.sh && ./stack.sh`` to see your
136 
+changes in action.
137 
+
138 
+To figure out the repo / branch names for every library that's
139 
+supported, you'll need to read the devstack source.
doc/source/index.rst
History View file @ bd6614a
... ... 
@@ -113,6 +113,9 @@ You can ``source openrc`` in your shell, and then use the
113 113 
 You can ``cd /opt/stack/tempest`` and run tempest tests that have
114 114 
 been configured to work with your devstack.
115 115
116 
+You can :doc:`make code changes to OpenStack and validate them
117 
+<development>`.
118 
+
116 119 
 Going further
117 120 
 -------------
118 121
doc/source/site-map.rst
History View file @ bd6614a
... ... 
@@ -17,5 +17,6 @@
17 17 
    plugins
18 18 
    plugin-registry
19 19 
    faq
20 
+   development
20 21 
    hacking
21 22 
    guides