Add DEVELOPMENT.md (#901)

* Add DEVELOPMENT.md

This DEVELOPMENT.md will hopefully help folks ramp up and get started
contributing to skaffold by describing the development process.

After discussions with @r2d4 and @balopat we want to try out keeping the
contributor/developer docs in markdown, while the user facing docs will
continue to be in asciidoc. One of the reasons for this is that github
will automatically link to the CONTRIBUTING.md and code of conduct, and
so if we wrote this in ascii doc, we would _have_ to make the docs (and
any references, links, etc.) that they contain work for both markdown
view in github and ascii doctor view in the generated docs.

* Explain how docs are published

CONTRIBUTING.adoc → CONTRIBUTING.md

@@ -1,29 +1,26 @@
+# How to Contribute
 
-= How to Contribute
 We'd love to accept your patches and contributions to this project. There are
 just a few small guidelines you need to follow.
 
-== Contributor License Agreement
+When you are ready to get started developing, see
+[DEVELOPMENT.md](./DEVELOPMENT.md) for how to get started!
+
+## Contributor License Agreement
 
 Contributions to this project must be accompanied by a Contributor License
 Agreement. You (or your employer) retain the copyright to your contribution,
 this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
+part of the project. Head over to
+[https://cla.developers.google.com/](https://cla.developers.google.com) to see
 your current agreements on file or to sign a new one.
 You generally only need to submit a CLA once, so if you've already submitted one
 (even if it was for a different project), you probably don't need to do it
 again.
 
-== Code reviews
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
-
-== Contributing to documentation
-Contributing to docs is the same process as the code reviews - except that we recommend that you locally you can check the generated docs with 
-```
-make docs
-```
-And then open the generated docs/generated folder for `index.html` and `index.pdf`.
+## Code reviews
 
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult the developer docs for more
+info on [creating pull requests](DEVELOPMENT.md#creating-a-pr)
+and [the Skaffold review process](DEVELOPMENT.md#reviews).

DEVELOPMENT.md

@@ -0,0 +1,140 @@
+# Development
+
+This doc explains the development workflow so you can get started
+[contributing](CONTRIBUTING.md) to Skaffold!
+
+## Getting started
+
+First you will need to setup your GitHub account and create a fork:
+
+1. Create [a GitHub account](https://github.com/join)
+1. Setup [GitHub access via
+   SSH](https://help.github.com/articles/connecting-to-github-with-ssh/)
+1. [Create and checkout a repo fork](#checkout-your-fork)
+
+Once you have those, you can iterate on skaffold:
+
+1. [Build your dev version of skaffold](#building-skaffold)
+1. [Verify changes locally](#verifying-local-changes)
+1. [Run skaffold tests](#testing-skaffold)
+1. [Build docs](#building-skaffold-docs) if you are making doc changes
+
+When you're ready, you can [create a PR](#creating-a-pr)!
+
+You may also be interested in [contributing to the docs](#contributing-to-skaffold-docs).
+
+## Checkout your fork
+
+The Go tools require that you clone the repository to the `src/github.com/GoogleContainerTools/skaffold` directory
+in your [`GOPATH`](https://github.com/golang/go/wiki/SettingGOPATH).
+
+To check out this repository:
+
+1. Create your own [fork of this
+  repo](https://help.github.com/articles/fork-a-repo/)
+
+1. Clone it to your machine:
+
+   ```shell
+   mkdir -p ${GOPATH}/src/github.com/GoogleContainerTools
+   cd ${GOPATH}/src/github.com/GoogleContainerTools
+   git clone [email protected]:${YOUR_GITHUB_USERNAME}/skaffold.git
+   cd skaffold
+   git remote add upstream [email protected]:GoogleContainerTools/skaffold.git
+   git remote set-url --push upstream no_push
+   ```
+
+   _Adding the `upstream` remote sets you up nicely for regularly [syncing your
+   fork](https://help.github.com/articles/syncing-a-fork/)._
+
+## Building skaffold
+
+To build with your local changes you have two options:
+
+1. Build the skaffold binary:
+
+   ```shell
+   make
+   ./out/skaffold version
+   ```
+
+   You can then run this binary directly, or copy/symlink it into your path.
+
+1. Build and install the skaffold binary:
+
+   ```shell
+   make install
+   skaffold version
+   ```
+
+   This will install skaffold via `go install` (note that if you have [manually downloaded
+   and installed skaffold to `/usr/bin/local`](README.adoc#installation), this is will probably
+   take precedence in your path over your `$GOPATH/bin`).
+
+   _If you are unsure if you are running a released or locally built version of skaffold, you
+   can run `skaffold version` - output which includes `dirty` indicates you have built the
+   binary locally._
+
+## Verifying local changes
+
+If you are iterating on skaffold and want to see your changes in action, you can:
+
+1. [Build skaffold](#building-and-running-skaffold)
+2. [Use the quickstart example](README.adoc#iterative-development)
+
+## Testing skaffold
+
+skaffold has both [unit tests](#unit-tests) and [integration tests](#integration-tests).
+
+### Unit Tests
+
+The unit tests live with the code they test and can be run with:
+
+```shell
+make test
+```
+
+_These tests will not run correctly unless you have [checked out your fork into your `$GOPATH`](#checkout-your-fork)._
+
+### Integration tests
+
+The integration tests live in [`integration`](./integration) and run the [`examples`](./examples)
+as tests. They can be run with:
+
+```shell
+make integration-test
+```
+
+_These tests require push access to a project in GCP, and so can only be run
+by maintainers who have access. These tests will be kicked off by [reviewers](#reviews)
+for submitted PRs._
+
+## Building skaffold docs
+
+Before [creating a PR](#creating-a-pr) with doc changes, we recommend that you locally verify the
+generated docs with:
+
+```shell
+make docs
+```
+
+And then open the generated docs/generated folder for `index.html` and `index.pdf`.
+
+Once PRs with doc changes are merged, they will get automatically published to the docs
+for [the latest build](https://storage.googleapis.com/skaffold/builds/latest/docs/index.html)
+which at release time will be published with [the latest release](https://storage.googleapis.com/skaffold/releases/latest/docs/index.html).
+
+## Creating a PR
+
+When you have changes you would like to propose to skaffold, you will need to:
+
+1. Ensure the commit message(s) describe what issue you are fixing and how you are fixing it
+   (include references to [issue numbers](https://help.github.com/articles/closing-issues-using-keywords/)
+   if appropriate)
+1. [Create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)
+
+### Reviews
+
+Each PR must be reviewed by a maintainer. This maintainer will add the `kokoro:run` label
+to a PR to kick of [the integration tests](#integration-tests), which must pass for the PR
+to be submitted.

README.adoc

@@ -108,8 +108,9 @@ git clone https://github.com/GoogleContainerTools/skaffold
 [source,shell]
 cd examples/getting-started
 
-. Run `skaffold dev`.
+. Replace `k8s-project` with your GCP project ID.
 
+. Run `skaffold dev`.
 [source,console]
 $ skaffold dev
 Starting build...

docs/index.adoc

@@ -45,7 +45,11 @@ include::../examples/README.adoc[]
 
 = Contributing
 
-include::../CONTRIBUTING.adoc[leveloffset=+1]
+See http://github.com/GoogleContainerTools/skaffold/tree/master/CONTRIBUTING.md[CONTRIBUTING.md]
+
+== Development
+
+See http://github.com/GoogleContainerTools/skaffold/tree/master/DEVELOPMENT.md[DEVELOPMENT.md]
 
 == Code of conduct
 

examples/README.adoc

@@ -1,7 +1,7 @@
 == Examples
 :icons: font
 
-To run any of the examples, just replace `k8s-project` with your GCP project ID.
+To run any of the examples, replace `k8s-project` with your GCP project ID.
 
 ifndef::env-github[]