docs: Add initial contributors' guide

This change introduces an initial contributors' guide, with the
intention of providing a starting point for developers interested in
contributing to Airship.

Future changes should expand on this documentation, including the
addition of documentation that covers the spec design and approval
process, standards and conventions for Helm charts, and how versions are
controlled in Airship.

Change-Id: Ifd146549d0707f9db2aefaefbadc77e47a1546e3
Story: 2005122
This commit is contained in:
Drew Walters 2019-03-27 19:06:56 +00:00
parent 0ebc90577a
commit e0d1d7ab40
2 changed files with 243 additions and 0 deletions

View File

@ -0,0 +1,242 @@
=================
Development Guide
=================
Welcome
-------
Thank you for your interest in Airship. Our community is eager to help you
contribute to the success of our project and welcome you as a member of our
community!
We invite you to reach out to us at any time via the `Airship mailing list`_ or
`#airshipit IRC channel`_ on freenode.
Welcome aboard!
.. _Airship mailing list: http://lists.airshipit.org
.. _#airshipit IRC channel: irc://chat.freenode.net:6667
Getting Started
---------------
Airship is a collection of open source tools for automating cloud provisioning
and management. Airship provides a declarative framework for defining and
managing the life cycle of open infrastructure tools and the underlying
hardware. These tools include OpenStack for virtual machines, Kubernetes for
container orchestration, and MaaS for bare metal, with planned support for
OpenStack Ironic.
We recommend that new contributors begin by reading the high-level architecture
overview included in our `treasuremap`_ documentation. The architectural
overview introduces each Airship component, their core responsibilities, and
their integration points.
.. _treasuremap: https://airship-treasuremap.readthedocs.io/en/latest
Deep Dive
---------
Each Airship component is accompanied by its own documentation that provides an
extensive overview of the component. With so many components, it can be
challenging to find a starting point.
We recommend the following:
Try an Airship environment
~~~~~~~~~~~~~~~~~~~~~~~~~~
Airship provides two single-node environments for demo and development purpose.
`Airship-in-a-Bottle`_ is a set of reference documents and shell scripts that
stand up a full Airship environment with the execution of a script.
`Airskiff`_ is a light-weight development environment bundled with a set of
deployment scripts that provides a single-node Airship environment. Airskiff
uses minikube to bootstrap Kubernetes, so it does not include Drydock, MaaS, or
Promenade.
Additionally, we provide a reference architecture for easily deploying a
smaller, demo site.
`Airsloop`_ is a fully-authored Airship site that can be quickly deployed as a
baremetal, demo lab.
.. _Airship-in-a-Bottle: https://opendev.org/airship/in-a-bottle
.. _Airskiff: https://airship-treasuremap.readthedocs.io/en/latest/airskiff.html
.. _Airsloop: https://airship-treasuremap.readthedocs.io/en/latest/airsloop.html
Focus on a component
~~~~~~~~~~~~~~~~~~~~
When starting out, focusing on one Airship component allows you to become
intricately familiar with the responsibilities of that component and understand
its function in the Airship integration. Because the components are modeled
after each other, you will also become familiar with the same patterns and
conventions that all Airship components use.
Airship source code lives in the `OpenDev Airship namespace`_. To clone an
Airship project, execute the following, replacing `<component>` with the name
of the Airship component you want to clone.
.. code-block bash::
git clone https://opendev.org/airship/<component>.git
Refer to the component's documentation to get started. A list of each
component's documentation is listed below for reference:
* `Armada`_
* `Deckhand`_
* `Divingbell`_
* `Drydock`_
* `Pegleg`_
* `Promenade`_
* `Shipyard`_
.. _OpenDev Airship namespace: https://opendev.org/airship
.. _Armada: https://airship-armada.readthedocs.io
.. _Deckhand: https://airship-deckhand.readthedocs.io
.. _Divingbell: https://airship-divingbell.readthedocs.io
.. _Drydock: https://airship-drydock.readthedocs.io
.. _Pegleg: https://airship-pegleg.readthedocs.io
.. _Promenade: https://airship-promenade.readthedocs.io
.. _Shipyard: https://airship-shipyard.readthedocs.io
Find a Storyboard task or story
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Airship work items are tracked using Storyboard. A board of items can be found
`here`_.
Once you find an item to work on, simply assign the item to yourself or leave a
comment that you plan to provide implementation for the item.
.. _here: https://storyboard.openstack.org/#!/project_group/85
Testing Changes
---------------
Testing of Airship changes can be accomplished several ways:
#. Standalone, single component testing
#. Integration testing
#. Linting, unit, and functional tests/linting
.. note:: Testing changes to charts in Airship repositories is best
accomplished using the integration method describe below.
Standalone Testing
~~~~~~~~~~~~~~~~~~
Standalone testing of Airship components, i.e. using an Airship component as a
Python project, provides the quickest feedback loop of the three methods and
allows developers to make changes on the fly. We recommend testing initial code
changes using this method to see results in real-time.
Each Airship component written in Python has pre-requisites and guides for
running the project in a standalone capacity. Refer to the documentation listed
below.
* `Armada`_
* `Deckhand`_
* `Drydock`_
* `Pegleg`_
* `Promenade`_
* `Shipyard`_
Integration Testing
~~~~~~~~~~~~~~~~~~~
While each Airship component supports individual usage, Airship components
have several integration points that should be exercised after modifying
functionality.
We maintain several environments that encompass these integration points:
#. `Airskiff`_: Integration of Armada, Deckhand, Shipyard, and Pegleg
#. `Airship-in-a-Bottle Multinode`: Full Airship integration
For changes that merely impact software delivery components, exercising a full
Airskiff deployment is often sufficient. Otherwise, we recommend using the
Airship-in-a-Bottle Multinode environment.
Each environment's documentation covers the process required to build and test
component images.
.. _Airskiff: https://airship-treasuremap.readthedocs.io/en/latest/
airskiff.html
.. _Airship-in-a-Bottle Multinode: http://git.openstack.org/cgit/openstack/
airship-in-a-bottle/tree/tools/multi_nodes_gate/README.rst
Final Checks
~~~~~~~~~~~~
Airship projects provide Makefiles to run unit, integration, and functional
tests as well as lint Python code for PEP8 compliance and Helm charts for
successful template rendering. All checks are gated by Zuul before a change can
be merged. For more information on executing these checks, refer to
project-specific documentation.
Third party CI tools, such as Jenkins, report results on Airship-in-a-Bottle
patches. These can be exposed using the "Toggle CI" button in the bottom
left-hand page of any gerrit change.
Pushing code
------------
Airship uses the `OpenDev gerrit`_ for code review. Refer to the `OpenStack
Contributing Guide`_ for a tutorial on submitting changes to Gerrit code
review.
.. _OpenDev gerrit: https://review.opendev.org
.. _OpenStack Contributing Guide: https://docs.openstack.org/horizon/latest/contributor/contributing.html
Next steps
----------
Upon pushing a change to gerrit, Zuul continuous integration will post job
results on your patch. Refer to the job output by clicking on the job itself to
determine if further action is required. If it's not clear why a job failed,
please reach out to a team member in IRC. We are happy to assist!
Assuming all continuous integration jobs succeed, Airship community members and
core developers will review your patch and provide feedback. Many patches are
submitted to Airship projects each day. If your patch does not receive feedback
for several days, please reach out using IRC or the Airship mailing list.
Merging code
------------
Like most OpenDev projects, Airship patches require two +2 code review votes
from core members to merge. Once you have addressed all outstanding feedback,
your change will be merged.
Beyond
------
Congratulations! After your first change merges, please keep up-to-date with
the team. We hold two weekly meetings for project and design discussion:
Our weekly #airshipit IRC meeting provides an opportunity to discuss project
operations.
Our weekly design call provides an opportunity for in-depth discussion of new
and existing Airship features.
For more information on the times of each meeting, refer to the `Airship
wiki`_.
.. _Airship wiki: https://wiki.openstack.org/wiki/Airship

View File

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