Initial Contributions and Developer Docs
This commit forms a starting point for our CONTRIBUTING.md and developer documentation. Change-Id: I7de8ad19e658a849208c18a3339c1f01a95471d5
This commit is contained in:
Alan Meadows
parent
9503619755
commit
7328c22a3e
|
|
@ -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).
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue