diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 00336c131..3e48e2b70 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/docs/developers.md b/docs/developers.md index 03dc81a10..61c65d4c0 100644 --- a/docs/developers.md +++ b/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 -project: +### 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 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 -https://github.com/deis/workflow/blob/master/src/contributing/submitting-a-pull-request.md +Conventions: +- 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.