Browse Source

Merge "docs: Add initial contributors' guide"

changes/15/656215/1
Zuul 3 weeks ago
parent
commit
74e6baf65e
2 changed files with 243 additions and 0 deletions
  1. 242
    0
      doc/source/development_guide.rst
  2. 1
    0
      doc/source/index.rst

+ 242
- 0
doc/source/development_guide.rst View File

@@ -0,0 +1,242 @@
1
+=================
2
+Development Guide
3
+=================
4
+
5
+Welcome
6
+-------
7
+
8
+Thank you for your interest in Airship. Our community is eager to help you
9
+contribute to the success of our project and welcome you as a member of our
10
+community!
11
+
12
+We invite you to reach out to us at any time via the `Airship mailing list`_ or
13
+`#airshipit IRC channel`_ on freenode.
14
+
15
+Welcome aboard!
16
+
17
+.. _Airship mailing list: http://lists.airshipit.org
18
+
19
+.. _#airshipit IRC channel: irc://chat.freenode.net:6667
20
+
21
+Getting Started
22
+---------------
23
+
24
+Airship is a collection of open source tools for automating cloud provisioning
25
+and management. Airship provides a declarative framework for defining and
26
+managing the life cycle of open infrastructure tools and the underlying
27
+hardware. These tools include OpenStack for virtual machines, Kubernetes for
28
+container orchestration, and MaaS for bare metal, with planned support for
29
+OpenStack Ironic.
30
+
31
+We recommend that new contributors begin by reading the high-level architecture
32
+overview included in our `treasuremap`_ documentation. The architectural
33
+overview introduces each Airship component, their core responsibilities, and
34
+their integration points.
35
+
36
+.. _treasuremap: https://airship-treasuremap.readthedocs.io/en/latest
37
+
38
+Deep Dive
39
+---------
40
+
41
+Each Airship component is accompanied by its own documentation that provides an
42
+extensive overview of the component. With so many components, it can be
43
+challenging to find a starting point.
44
+
45
+We recommend the following:
46
+
47
+Try an Airship environment
48
+~~~~~~~~~~~~~~~~~~~~~~~~~~
49
+
50
+Airship provides two single-node environments for demo and development purpose.
51
+
52
+`Airship-in-a-Bottle`_ is a set of reference documents and shell scripts that
53
+stand up a full Airship environment with the execution of a script.
54
+
55
+`Airskiff`_ is a light-weight development environment bundled with a set of
56
+deployment scripts that provides a single-node Airship environment. Airskiff
57
+uses minikube to bootstrap Kubernetes, so it does not include Drydock, MaaS, or
58
+Promenade.
59
+
60
+Additionally, we provide a reference architecture for easily deploying a
61
+smaller, demo site.
62
+
63
+`Airsloop`_ is a fully-authored Airship site that can be quickly deployed as a
64
+baremetal, demo lab.
65
+
66
+.. _Airship-in-a-Bottle: https://opendev.org/airship/in-a-bottle
67
+
68
+.. _Airskiff: https://airship-treasuremap.readthedocs.io/en/latest/airskiff.html
69
+
70
+.. _Airsloop: https://airship-treasuremap.readthedocs.io/en/latest/airsloop.html
71
+
72
+Focus on a component
73
+~~~~~~~~~~~~~~~~~~~~
74
+
75
+When starting out, focusing on one Airship component allows you to become
76
+intricately familiar with the responsibilities of that component and understand
77
+its function in the Airship integration. Because the components are modeled
78
+after each other, you will also become familiar with the same patterns and
79
+conventions that all Airship components use.
80
+
81
+Airship source code lives in the `OpenDev Airship namespace`_. To clone an
82
+Airship project, execute the following, replacing `<component>` with the name
83
+of the Airship component you want to clone.
84
+
85
+.. code-block bash::
86
+
87
+  git clone https://opendev.org/airship/<component>.git
88
+
89
+Refer to the component's documentation to get started. A list of each
90
+component's documentation is listed below for reference:
91
+
92
+    * `Armada`_
93
+    * `Deckhand`_
94
+    * `Divingbell`_
95
+    * `Drydock`_
96
+    * `Pegleg`_
97
+    * `Promenade`_
98
+    * `Shipyard`_
99
+
100
+.. _OpenDev Airship namespace: https://opendev.org/airship
101
+
102
+.. _Armada: https://airship-armada.readthedocs.io
103
+
104
+.. _Deckhand: https://airship-deckhand.readthedocs.io
105
+
106
+.. _Divingbell: https://airship-divingbell.readthedocs.io
107
+
108
+.. _Drydock: https://airship-drydock.readthedocs.io
109
+
110
+.. _Pegleg: https://airship-pegleg.readthedocs.io
111
+
112
+.. _Promenade: https://airship-promenade.readthedocs.io
113
+
114
+.. _Shipyard: https://airship-shipyard.readthedocs.io
115
+
116
+Find a Storyboard task or story
117
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
118
+
119
+Airship work items are tracked using Storyboard. A board of items can be found
120
+`here`_.
121
+
122
+Once you find an item to work on, simply assign the item to yourself or leave a
123
+comment that you plan to provide implementation for the item.
124
+
125
+.. _here: https://storyboard.openstack.org/#!/project_group/85
126
+
127
+Testing Changes
128
+---------------
129
+
130
+Testing of Airship changes can be accomplished several ways:
131
+
132
+    #. Standalone, single component testing
133
+    #. Integration testing
134
+    #. Linting, unit, and functional tests/linting
135
+
136
+.. note:: Testing changes to charts in Airship repositories is best
137
+    accomplished using the integration method describe below.
138
+
139
+Standalone Testing
140
+~~~~~~~~~~~~~~~~~~
141
+
142
+Standalone testing of Airship components, i.e. using an Airship component as a
143
+Python project, provides the quickest feedback loop of the three methods and
144
+allows developers to make changes on the fly. We recommend testing initial code
145
+changes using this method to see results in real-time.
146
+
147
+Each Airship component written in Python has pre-requisites and guides for
148
+running the project in a standalone capacity. Refer to the documentation listed
149
+below.
150
+
151
+    * `Armada`_
152
+    * `Deckhand`_
153
+    * `Drydock`_
154
+    * `Pegleg`_
155
+    * `Promenade`_
156
+    * `Shipyard`_
157
+
158
+Integration Testing
159
+~~~~~~~~~~~~~~~~~~~
160
+
161
+While each Airship component supports individual usage, Airship components
162
+have several integration points that should be exercised after modifying
163
+functionality.
164
+
165
+We maintain several environments that encompass these integration points:
166
+
167
+    #. `Airskiff`_: Integration of Armada, Deckhand, Shipyard, and Pegleg
168
+    #. `Airship-in-a-Bottle Multinode`: Full Airship integration
169
+
170
+For changes that merely impact software delivery components, exercising a full
171
+Airskiff deployment is often sufficient. Otherwise, we recommend using the
172
+Airship-in-a-Bottle Multinode environment.
173
+
174
+Each environment's documentation covers the process required to build and test
175
+component images.
176
+
177
+.. _Airskiff: https://airship-treasuremap.readthedocs.io/en/latest/
178
+    airskiff.html
179
+
180
+.. _Airship-in-a-Bottle Multinode: http://git.openstack.org/cgit/openstack/
181
+    airship-in-a-bottle/tree/tools/multi_nodes_gate/README.rst
182
+
183
+Final Checks
184
+~~~~~~~~~~~~
185
+
186
+Airship projects provide Makefiles to run unit, integration, and functional
187
+tests as well as lint Python code for PEP8 compliance and Helm charts for
188
+successful template rendering. All checks are gated by Zuul before a change can
189
+be merged. For more information on executing these checks, refer to
190
+project-specific documentation.
191
+
192
+Third party CI tools, such as Jenkins, report results on Airship-in-a-Bottle
193
+patches. These can be exposed using the "Toggle CI" button in the bottom
194
+left-hand page of any gerrit change.
195
+
196
+Pushing code
197
+------------
198
+
199
+Airship uses the `OpenDev gerrit`_ for code review. Refer to the `OpenStack
200
+Contributing Guide`_ for a tutorial on submitting changes to Gerrit code
201
+review.
202
+
203
+.. _OpenDev gerrit: https://review.opendev.org
204
+
205
+.. _OpenStack Contributing Guide: https://docs.openstack.org/horizon/latest/contributor/contributing.html
206
+
207
+Next steps
208
+----------
209
+
210
+Upon pushing a change to gerrit, Zuul continuous integration will post job
211
+results on your patch. Refer to the job output by clicking on the job itself to
212
+determine if further action is required. If it's not clear why a job failed,
213
+please reach out to a team member in IRC. We are happy to assist!
214
+
215
+Assuming all continuous integration jobs succeed, Airship community members and
216
+core developers will review your patch and provide feedback. Many patches are
217
+submitted to Airship projects each day. If your patch does not receive feedback
218
+for several days, please reach out using IRC or the Airship mailing list.
219
+
220
+Merging code
221
+------------
222
+
223
+Like most OpenDev projects, Airship patches require two +2 code review votes
224
+from core members to merge. Once you have addressed all outstanding feedback,
225
+your change will be merged.
226
+
227
+Beyond
228
+------
229
+
230
+Congratulations! After your first change merges, please keep up-to-date with
231
+the team. We hold two weekly meetings for project and design discussion:
232
+
233
+Our weekly #airshipit IRC meeting provides an opportunity to discuss project
234
+operations.
235
+
236
+Our weekly design call provides an opportunity for in-depth discussion of new
237
+and existing Airship features.
238
+
239
+For more information on the times of each meeting, refer to the `Airship
240
+wiki`_.
241
+
242
+.. _Airship wiki: https://wiki.openstack.org/wiki/Airship

+ 1
- 0
doc/source/index.rst View File

@@ -198,6 +198,7 @@ Process Flows
198 198
    seaworthy
199 199
    airsloop
200 200
    airskiff
201
+   development_guide
201 202
 
202 203
 .. _Barbican: https://docs.openstack.org/barbican/latest/api/
203 204
 .. _Helm Homepage: https://helm.sh/

Loading…
Cancel
Save