airship/airshipctl
Code Issues Proposed changes

Merge "Initial Contributions and Developer Docs"

Browse Source
This commit is contained in:
Zuul 2019-11-07 20:56:39 +00:00 committed by Gerrit Code Review
commit d462b8a014
2 changed files with 143 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
CONTRIBUTING.md Normal file
View File

@ -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).

101
docs/developers.md Normal file
View File

@ -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.