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
parent
0ebc90577a
commit
e0d1d7ab40
242
doc/source/development_guide.rst
Normal file
242
doc/source/development_guide.rst
Normal 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
|
||||
@ -198,6 +198,7 @@ Process Flows
|
||||
seaworthy
|
||||
airsloop
|
||||
airskiff
|
||||
development_guide
|
||||
|
||||
.. _Barbican: https://docs.openstack.org/barbican/latest/api/
|
||||
.. _Helm Homepage: https://helm.sh/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user