From e650468379f12f1437a000cddd6d354bde3802d3 Mon Sep 17 00:00:00 2001 From: Noor Muhammad Malik Date: Thu, 2 Apr 2020 20:46:10 +0500 Subject: [PATCH] Create documentation for new developers 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 --- docs/source/developers.md | 157 +++++++++++++++++++++++++------------- 1 file changed, 103 insertions(+), 54 deletions(-) diff --git a/docs/source/developers.md b/docs/source/developers.md index f8d00c8f9..1047042fd 100644 --- a/docs/source/developers.md +++ b/docs/source/developers.md @@ -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/