diff --git a/doc/source/development_guide.rst b/doc/source/development_guide.rst new file mode 100644 index 000000000..95a3b77c6 --- /dev/null +++ b/doc/source/development_guide.rst @@ -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 `` with the name +of the Airship component you want to clone. + +.. code-block bash:: + + git clone https://opendev.org/airship/.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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 5fb6389d0..dd2581242 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -198,6 +198,7 @@ Process Flows seaworthy airsloop airskiff + development_guide .. _Barbican: https://docs.openstack.org/barbican/latest/api/ .. _Helm Homepage: https://helm.sh/