Merge "Initial Contributions and Developer Docs"

CONTRIBUTING.md

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

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.