diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..52bdd48e1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,42 @@ +# Contributing Guidelines + +The airshipctl project accepts contributions via gerrit reviews. For help +getting started with gerrit, see the official [OpenDev +documentation](https://docs.openstack.org/contributors/common/setup-gerrit.html). +This document outlines the process to help get your contribution accepted. + +## Support Channels + +Whether you are a user or contributor, official support channels are available +[here](https://wiki.openstack.org/wiki/Airship#Get_in_Touch) + +You can also report [bugs](https://airship.atlassian.net/issues/?jql=project%20%3D%20AIR%20AND%20issuetype%20%3D%20Bug%20order%20by%20created%20DESC). + + +Before opening a new issue or submitting a patchset, it's helpful to search the +bug reports above - it's likely that another user has already reported the issue you're +facing, or it's a known issue that we're already aware of. It is also worth +asking on the IRC channels. + +## Story Lifecycle + +The airshipctl project uses Jira to track all efforts, whether those are +contributions to this repository or other community projects. The Jira issues +are a combination of epics, issues, subtasks, bugs, and milestones. We use +epics to define large deliverables and many epics have been created already. +The project assumes that developers trying to break down epics into managable +work will create their own issues/stories and any related subtasks to further +breakdown their work. Milestones act as human readable goals for the sprint they +are assigned to. + +- [Active Sprints](https://airship.atlassian.net/secure/RapidBoard.jspa?rapidView=1) +- [Issues](https://airship.atlassian.net/projects/AIR/issues) + +The airshipctl project leverages 1-month sprints primarily for the purpose of +chronologically ordering work in Jira. + +### Coding Conventions + +Airship has a set of [coding conventions](https://airship-docs.readthedocs.io/en/latest/conventions.html) that are meant to cover all Airship subprojects. + +However, airshipctl also has its own specific coding conventions and standards in the official airshipctl [developer guide](docs/developers.md). \ No newline at end of file diff --git a/docs/developers.md b/docs/developers.md new file mode 100644 index 000000000..58c23c23d --- /dev/null +++ b/docs/developers.md @@ -0,0 +1,101 @@ +# Developers Guide + +This guide explains how to set up your environment for developing on +airshipctl. + +## Environment Expectations + +- Go 1.13 +- Docker +- Git + +## Building airshipctl + +We use Make to build our programs. The simplest way to get started is: + +```console +$ make build +``` + +NOTE: The airshipctl application is a go module. This means you do not need to +clone the repository into `$GOPATH` in order to build it. You should be able to +build it from any directory. + +This will build the airshipctl binary. + +To run all the tests including linting and coverage reports, run `make test`. To +run all tests in a containerized environment, run `make docker-image-unit-tests` +or `make docker-image-lint` + +To run airshipctl locally, you can run `bin/airshipctl`. + +## Docker Images + +If you want to build an `airshipctl` Docker container, run `make docker-image`. + +To build Docker images, use `make docker-image`. + +Pre-built images are already available at [quay.io](http://quay.io/airshipit/airshipctl). + +## Contribution Guidelines + +We welcome contributions. This project has set up some guidelines in order to +ensure that (a) code quality remains high, (b) the project remains consistent, +and (c) contributions follow the open source legal requirements. Our intent is +not to burden contributors, but to build elegant and high-quality open source +code so that our users will benefit. + +Make sure you have read and understood the main airshipctl [Contributing +Guide](/CONTRIBUTING.md) + +### Structure of the Code + +The code for the airshipctl project is organized as follows: + +- The individual programs are located in `cmd/`. Code inside of `cmd/` is not + designed for library re-use. +- Shared libraries are stored in `pkg/`. +- Both commands and shared libraries may require test data fixtures. These + should be placed in a `testdata/` subdirectory within the command or library. +- The `testutil/` directory contains functions that are helpful for unit tests. +- The `zuul.d/` directory contains Zuul YAML definitions for CI/CD jobs to run. +- The `playbooks/` directory contains playbooks that the Zuul CI/CD jobs will run. +- The `tools/` directory contains scripts used by the Makefile and CI/CD pipeline. +- The `docs/` folder is used for documentation and examples. + +Go dependencies are managed by `go mod` and stored in `go.mod` and `go.sum` + +### Git Conventions + +We use Git for our version control system. The `master` branch is the home of +the current development candidate. Releases are tagged. + +We accept changes to the code via Gerrit pull requests. One workflow for doing +this is as follows: + +1. `git clone` the `opendev.org/airship/airshipctl` repository. +2. Create a new working branch (`git checkout -b feat/my-feature`) and do your + work on that branch. +3. When you are ready for us to review, push your branch to gerrit using + `git-review`. For more information on the gerrit workflow, see the [OpenDev + documentation](https://docs.openstack.org/contributors/common/setup-gerrit.html). + +### Go Conventions + +We follow the Go coding style standards very closely. Typically, running `go +fmt` will make your code beautiful for you. + +We also typically follow the conventions of `golangci-lint`. + +Read more: + +- Effective Go [introduces + formatting](https://golang.org/doc/effective_go.html#formatting). +- The Go Wiki has a great article on + [formatting](https://github.com/golang/go/wiki/CodeReviewComments). + +### Testing + +In order to ensure that all package unit tests follow the same standards and use +the same frameworks, airshipctl has a document outlining [specific test +guidelines](/docs/testing-guidelines.md) maintained separately.