airship/airshipctl
Code Issues Proposed changes

Create documentation for new developers

Browse Source 
This patch updates the develop documentation in docs/source/developers.md.
Adds details on environment setup and uses some of the scripts available
in tools/gate directory.

Change-Id: I76d426746f668f89ab4f9e43ac00f75f47735702
Relates-To: #72
Closes: #72
This commit is contained in:
Noor Muhammad Malik 2020-04-02 20:46:10 +05:00
parent bc949f259f
commit e650468379
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
airshipctl.
## Environment Expectations
## Environment expectations
- Git
- Go 1.13
- 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
We use Make to build our programs. The simplest way to get started is:
The simplest way to get started is:
```console
$ make build
```sh
git clone https://opendev.org/airship/airshipctl.git
```
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.
NOTE: The airshipctl application is a Go module. This means that there is no
need to clone the repository into the $GOPATH directory in order to build it.
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
run all tests in a containerized environment, run `make docker-image-unit-tests`
or `make docker-image-lint`
```sh
make build
```
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
If you want to build an `airshipctl` Docker image, run `make docker-image`.
Pre-built images are already available at [quay.io](
https://quay.io/airshipit/airshipctl).
Pre-built images are already available at [quay.io][2]. Moreover, in the
directory `airshipctl/tools/gate/`, different scripts are present which will
run and download all the required images. The script [10_build_gate.sh][3]
will download all the required images.
## 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.
ensure that
Make sure you have read and understood the main airshipctl [Contributing
Guide](../../CONTRIBUTING.md)
- code quality remains high
- 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 individual programs are located in `cmd/`. Code inside of `cmd/` is not
designed for library re-use.
- The client-facing code is located in `cmd/`. Code inside of `cmd/` is not
designed for library reuse.
- 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.
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.
run.
- 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.
- 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
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 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).
1. `git clone` the `airshipctl` repository. For this run the command:
### Go Conventions
```sh
git clone https://opendev.org/airship/airshipctl.git
```
We follow the Go coding style standards very closely. Typically, running `go
fmt -s -w ./` will make your code beautiful for you.
2. Use [OpenDev documentation][5] to setup Gerrit with the repo.
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`.
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).
- Effective Go [introduces formatting][7].
- The Go Wiki has a great article on [formatting][8].
### Testing
## 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](testing-guidelines.md) maintained separately.
In order to ensure that all package unit tests follow the same standard and
use the same frameworks, airshipctl has a document outlining
[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/