e0d1d7ab40
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
8.1 KiB
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!
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.
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.
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.
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:
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.
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.
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.
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.
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.