airship/airshipctl
Code Issues Proposed changes

Merge "Create documentation for new developers"

Browse Source
This commit is contained in:
Zuul 2020-04-08 15:58:57 +00:00 committed by Gerrit Code Review
commit a306429749
1 changed files with 103 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
docs/source/developers.md
View File

@ -1,103 +1,152 @@
# Developers Guide # Developer's Guide
This guide explains how to set up your environment for developing on This guide explains how to set up your environment for developing on
airshipctl. airshipctl.
## Environment Expectations ## Environment expectations
- Git
- Go 1.13 - Go 1.13
- Docker - Docker
- Git
### Installing Git
Instructions to install Git are [here][12].
### Installing Go 1.13
Instructions to install Golang are [here][13].
### Installing Docker
Instructions to install Docker are [here][14].
Additionally, there is a script in the airshipctl directory named as
`00_setup.sh`. This script will download all the required binaries and
packages. This script can be checked [here][1].
## Building airshipctl ## Building airshipctl
We use Make to build our programs. The simplest way to get started is: The simplest way to get started is:
```console ```sh
$ make build git clone https://opendev.org/airship/airshipctl.git
``` ```
NOTE: The airshipctl application is a Go module. This means you do not need to NOTE: The airshipctl application is a Go module. This means that there is no
clone the repository into `$GOPATH` in order to build it. You should be able to need to clone the repository into the $GOPATH directory in order to build it.
build it from any directory. You should be able to build it from any directory as long as $GOPATH is
defined correctly.
This will build the airshipctl binary. The following command will build the airshipctl binary.
To run all the tests including linting and coverage reports, run `make test`. To ```sh
run all tests in a containerized environment, run `make docker-image-unit-tests` make build
or `make docker-image-lint` ```
To run airshipctl locally, you can run `bin/airshipctl`. This will compile airshipctl and place the resulting binary into the bin
directory. 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-test-suite`.
## Docker Images ## Docker Images
If you want to build an `airshipctl` Docker image, run `make docker-image`. If you want to build an `airshipctl` Docker image, run `make docker-image`.
Pre-built images are already available at [quay.io][2]. Moreover, in the
Pre-built images are already available at [quay.io]( directory `airshipctl/tools/gate/`, different scripts are present which will
https://quay.io/airshipit/airshipctl). run and download all the required images. The script [10_build_gate.sh][3]
will download all the required images.
## Contribution Guidelines ## Contribution Guidelines
We welcome contributions. This project has set up some guidelines in order to 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, ensure that
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 - code quality remains high
Guide](../../CONTRIBUTING.md) - the project remains consistent, and
- contributions follow the open source legal requirements.
### Structure of the Code 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][4].
## Structure of the Code
The code for the airshipctl project is organized as follows: The code for the airshipctl project is organized as follows:
- The individual programs are located in `cmd/`. Code inside of `cmd/` is not - The client-facing code is located in `cmd/`. Code inside of `cmd/` is not
designed for library re-use. designed for library reuse.
- Shared libraries are stored in `pkg/`. - Shared libraries are stored in `pkg/`.
- Both commands and shared libraries may require test data fixtures. These - Both commands and shared libraries may require test data fixtures. These
should be placed in a `testdata/` subdirectory within the command or library. should be placed in a `testdata/` subdirectory within the command or library.
- The `testutil/` directory contains functions that are helpful for unit tests. - The `testutil/` directory contains functions that are helpful for unit
- The `zuul.d/` directory contains Zuul YAML definitions for CI/CD jobs to run. 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 - The `playbooks/` directory contains playbooks that the Zuul CI/CD jobs will
run. run.
- The `tools/` directory contains scripts used by the Makefile and CI/CD - The `tools/` directory contains scripts used by the Makefile and CI/CD
pipeline. pipeline.
- The `tools/gate` directory consists of different scripts. These scripts
will setup the environment as per requirements and install all the required
packages and binaries. This will also download all the required docker images.
- The `docs/` folder is used for documentation and examples. - The `docs/` folder is used for documentation and examples.
- Go dependencies are managed by `go mod` and stored in `go.mod` and `go.sum`
Go dependencies are managed by `go mod` and stored in `go.mod` and `go.sum` ## Git Conventions
### Git Conventions
We use Git for our version control system. The `master` branch is the home of We use Git for our version control system. The `master` branch is the home of
the current development candidate. Releases are tagged. the current development candidate. Releases are tagged.
We accept changes to the code via Gerrit pull requests. One workflow for doing We accept changes to the code via Gerrit pull requests. One workflow for doing
this is as follows: this is as follows:
1. `git clone` the `opendev.org/airship/airshipctl` repository. 1. `git clone` the `airshipctl` repository. For this run the command:
2. Create a new working branch (`git checkout -b feature/my-feature`) and do your
work on that branch. This will act as your topic in Gerrit.
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 ```sh
git clone https://opendev.org/airship/airshipctl.git
```
We follow the Go coding style standards very closely. Typically, running `go 2. Use [OpenDev documentation][5] to setup Gerrit with the repo.
fmt -s -w ./` will make your code beautiful for you.
3. When set, use [this guide][6] to learn the OpenDev development workflow,
in a sandbox environment. You can then apply the learnings to start developing
airshipctl.
## Go Conventions
We follow the Go coding style standards very closely. Typically, running
`goimports -w -local opendev.org/airship/airshipctl ./` will make your code
beautiful for you.
We also typically follow the conventions of `golangci-lint`. We also typically follow the conventions of `golangci-lint`.
Read more: Read more:
- Effective Go [introduces - Effective Go [introduces formatting][7].
formatting](https://golang.org/doc/effective_go.html#formatting). - The Go Wiki has a great article on [formatting][8].
- The Go Wiki has a great article on
[formatting](https://github.com/golang/go/wiki/CodeReviewComments).
### Testing ## Testing
In order to ensure that all package unit tests follow the same standards and use In order to ensure that all package unit tests follow the same standard and
the same frameworks, airshipctl has a document outlining [specific test use the same frameworks, airshipctl has a document outlining
guidelines](testing-guidelines.md) maintained separately. [specific test guidelines][9] maintained separately.
Moreover, there are few scripts in directory `tools/gate` which run different
tests. The script [20_run_test_runner.sh][10] will generate airshipctl config
file and verify cluster and kubectl version. The script
[22_test_config.sh][11] will generate kube config, set airshipctl config and
verify the cluster.
[1]: https://github.com/airshipit/airshipctl/blob/master/tools/gate/00_setup.sh
[2]: https://quay.io/airshipit/airshipctl
[3]: https://github.com/airshipit/airshipctl/blob/master/tools/gate/10_build_gate.sh
[4]: https://github.com/airshipit/airshipctl/blob/master/CONTRIBUTING.md
[5]: https://docs.openstack.org/contributors/common/setup-gerrit.html
[6]: https://docs.opendev.org/opendev/infra-manual/latest/sandbox.html
[7]: https://golang.org/doc/effective_go.html#formatting
[8]: https://github.com/golang/go/wiki/CodeReviewComments
[9]: https://github.com/airshipit/airshipctl/blob/master/docs/source/testing-guidelines.md
[10]: https://github.com/airshipit/airshipctl/blob/master/tools/gate/20_run_test_runner.sh
[11]: https://github.com/airshipit/airshipctl/blob/master/tools/gate/22_test_configs.sh
[12]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
[13]: https://golang.org/doc/install
[14]: https://docs.docker.com/get-docker/