Merge pull request #849 from technosophos/docs/840-dev-docs

docs(developer): update developer documentation

CONTRIBUTING.md

@@ -21,6 +21,10 @@ Follow either of the two links above to access the appropriate CLA and instructi
 1. Fork the desired repo, develop and test your code changes.
 1. Submit a pull request.
 
+Coding conventions and standards are explained in the official
+developer docs:
+https://github.com/kubernetes/helm/blob/master/docs/developers.md
+
 ### Merge Approval
 
 Helm collaborators may add "LGTM" (Looks Good To Me) or an equivalent comment to indicate that a PR is acceptable. Any change requires at least one LGTM.  No pull requests can be merged until at least one Helm collaborator signs off with an LGTM.

docs/developers.md

@@ -19,7 +19,8 @@ We use Make to build our programs. The simplest way to get started is:
 $ make boostrap build
 ```
 
-This will build both Helm and Tiller.
+This will build both Helm and Tiller. `make bootstrap` will attempt to
+install certain tools if they are missing.
 
 To run all of the tests (without running the tests for `vendor/`), run
 `make test`.
@@ -37,9 +38,12 @@ Helm and Tiller communicate using gRPC. To get started with gRPC, you will need
 
 - Install `protoc` for compiling protobuf files. Releases are
   [here](https://github.com/google/protobuf/releases)
-- Install the protoc Go plugin: `go get -u github.com/golang/protobuf/protoc-gen-go`
+- Run Helm's `make bootstrap` to generate the `protoc-gen-go` plugin and
+  place it in `bin/`.
 
-Note that you need to be on protobuf 3.x (`protoc --version`) and use the latest Go plugin.
+Note that you need to be on protobuf 3.x (`protoc --version`). The
+version of `protoc-gen-go` is tied to the version of gRPC used in
+Kubernetes. So the plugin is maintained locally.
 
 While the gRPC and ProtoBuf specs remain silent on indentation, we
 require that the indentation style matches the Go format specification.
@@ -55,7 +59,10 @@ To regenerate the Go files from the protobuf source, `make protoc`.
 
 ## Docker Images
 
-To build Docker images, use `make docker-build`
+To build Docker images, use `make docker-build`.
+
+Pre-build images are already available in the official Kubernetes Helm
+GCR registry.
 
 ## Running a Local Cluster
 
@@ -63,6 +70,8 @@ You can run tests locally using the `scripts/local-cluster.sh` script to
 start Kubernetes inside of a Docker container. For OS X, you will need
 to be running `docker-machine`.
 
+Tiller should run on any >= 1.2 Kubernetes cluster with beta extensions.
+
 ## Contribution Guidelines
 
 We welcome contributions. This project has set up some guidelines in
@@ -75,11 +84,86 @@ Make sure you have read and understood the main CONTRIBUTING guide:
 
 https://github.com/kubernetes/helm/blob/master/CONTRIBUTING.md
 
-We follow the coding standards and guidelines outlined by the Deis
+### Git Conventions
-project:
+
+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 GitHub Pull Requests (PRs). One
+workflow for doing this is as follows:
+
+1. Go to your `$GOPATH/k8s.io` directory and `git clone` the
+   `github.com/kubernetes/helm` repository.
+2. Fork that repository into your GitHub account
+3. Add your repository as a remote for `$GOPATH/k8s.io/helm`
+4. Create a new working branch (`git checkout -b feat/my-feature`) and
+   do your work on that branch.
+5. When you are ready for us to review, push your branch to GitHub, and
+   then open a new pull request with us.
+
+For Git commit messages, we follow the [Semantic Commit Messages](http://karma-runner.github.io/0.13/dev/git-commit-msg.html):
+
+```
+fix(helm): add --foo flag to 'helm install'
+
+When 'helm install --foo bar' is run, this will print "foo" in the
+output regardless of the outcome of the installation.
+
+Closes #1234
+```
+
+Common commit types:
+
+- fix: Fix a bug or error
+- feat: Add a new feature
+- docs: Change documentation
+- test: Improve testing
+
+Common scopes:
+
+- helm: The Helm CLI
+- tiller: The Tiller server
+- proto: Protobuf definitions
+- pkg/lint: The lint package. Follow a similar convention for any
+  package,
+- `*`: two or more scopes
+
+Read more:
+- The [Deis Guidelines](https://github.com/deis/workflow/blob/master/src/contributing/submitting-a-pull-request.md)
+  were the inspiration for this section.
+- Karma Runner [defines](http://karma-runner.github.io/0.13/dev/git-commit-msg.html) the semantic commit message idea.
+
+### 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 recommended by `go lint` and
+`govet`. Run `make test-style` to test the style conformance.
+
+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).
+
+### Protobuf Conventions
+
+Because this project is largely Go code, we format our Protobuf files as
+closely to Go as possible. There are currently no real formatting rules
+or guidelines for Protobuf, but as they emerge, we may opt to follow
+those instead.
+
+Standards:
+- Tabs for indentation, not spaces.
+- Spacing rules follow Go conventions (curly braces at line end, spaces
+  around operators).
 
-https://github.com/deis/workflow/blob/master/CONTRIBUTING.md
+Conventions:
-https://github.com/deis/workflow/blob/master/src/contributing/submitting-a-pull-request.md
+- Files should specify their package with `option go_package = "...";`
+- Comments should translate into good Go code comments (since `protoc`
+  copies comments into the destination source code file).
+- RPC functions are defined in the same file as their request/response
+  messages.
+- Deprecated RPCs, messages, and fields are marked deprecated in the comments (`// UpdateFoo
+  DEPRECATED updates a foo.`).
 
-Adidtionally, contributors must have a CLA with CNCF/Google before we can
-accept contributions.