github.com/caicloud/helm@v2.5.0+incompatible/docs/developers.md (about)

     1  # Developers Guide
     2  
     3  This guide explains how to set up your environment for developing on
     4  Helm and Tiller.
     5  
     6  ## Prerequisites
     7  
     8  - Go 1.6.0 or later
     9  - Glide 0.12.0 or later
    10  - kubectl 1.2 or later
    11  - A Kubernetes cluster (optional)
    12  - The gRPC toolchain
    13  - Git
    14  - Mercurial
    15  
    16  ## Building Helm/Tiller
    17  
    18  We use Make to build our programs. The simplest way to get started is:
    19  
    20  ```console
    21  $ make bootstrap build
    22  ```
    23  
    24  NOTE: This will fail if not run from the path: `$GOPATH/src/k8s.io/helm`.
    25  
    26  This will build both Helm and Tiller. `make bootstrap` will attempt to
    27  install certain tools if they are missing.
    28  
    29  To run all of the tests (without running the tests for `vendor/`), run
    30  `make test`.
    31  
    32  To run Helm and Tiller locally, you can run `bin/helm` or `bin/tiller`.
    33  
    34  - Helm and Tiller are known to run on macOS and most Linuxes, including
    35    Alpine.
    36  - Tiller must have access to a Kubernetes cluster. It learns about the
    37    cluster by examining the Kube config files that `kubectl` uses.
    38  
    39  ### Man pages
    40  
    41  Man pages and Markdown documentation are already pre-built in `docs/`. You may
    42  regenerate documentation using `make docs`.
    43  
    44  To expose the Helm man pages to your `man` client, you can put the files in your
    45  `$MANPATH`:
    46  
    47  ```
    48  $ export MANPATH=$GOPATH/src/k8s.io/helm/docs/man:$MANPATH
    49  $ man helm
    50  ```
    51  
    52  ## gRPC and Protobuf
    53  
    54  Helm and Tiller communicate using gRPC. To get started with gRPC, you will need to...
    55  
    56  - Install `protoc` for compiling protobuf files. Releases are
    57    [here](https://github.com/google/protobuf/releases)
    58  - Run Helm's `make bootstrap` to generate the `protoc-gen-go` plugin and
    59    place it in `bin/`.
    60  
    61  Note that you need to be on protobuf 3.2.0 (`protoc --version`). The
    62  version of `protoc-gen-go` is tied to the version of gRPC used in
    63  Kubernetes. So the plugin is maintained locally.
    64  
    65  While the gRPC and ProtoBuf specs remain silent on indentation, we
    66  require that the indentation style matches the Go format specification.
    67  Namely, protocol buffers should use tab-based indentation and rpc
    68  declarations should follow the style of Go function declarations.
    69  
    70  ### The Helm API (HAPI)
    71  
    72  We use gRPC as an API layer. See `pkg/proto/hapi` for the generated Go code,
    73  and `_proto` for the protocol buffer definitions.
    74  
    75  To regenerate the Go files from the protobuf source, `make protoc`.
    76  
    77  ## Docker Images
    78  
    79  To build Docker images, use `make docker-build`.
    80  
    81  Pre-build images are already available in the official Kubernetes Helm
    82  GCR registry.
    83  
    84  ## Running a Local Cluster
    85  
    86  For development, we highly recommend using the
    87  [Kubernetes Minikube](https://github.com/kubernetes/minikube)
    88  developer-oriented distribution. Once this is installed, you can use
    89  `helm init` to install into the cluster.
    90  
    91  For developing on Tiller, it is sometimes more expedient to run Tiller locally
    92  instead of packaging it into an image and running it in-cluster. You can do
    93  this by telling the Helm client to us a local instance.
    94  
    95  ```console
    96  $ make build
    97  $ bin/tiller
    98  ```
    99  
   100  And to configure the Helm client, use the `--host` flag or export the `HELM_HOST`
   101  environment variable:
   102  
   103  ```console
   104  $ export HELM_HOST=localhost:44134
   105  $ helm install foo
   106  ```
   107  
   108  (Note that you do not need to use `helm init` when you are running Tiller directly)
   109  
   110  Tiller should run on any >= 1.3 Kubernetes cluster.
   111  
   112  ## Contribution Guidelines
   113  
   114  We welcome contributions. This project has set up some guidelines in
   115  order to ensure that (a) code quality remains high, (b) the project
   116  remains consistent, and (c) contributions follow the open source legal
   117  requirements. Our intent is not to burden contributors, but to build
   118  elegant and high-quality open source code so that our users will benefit.
   119  
   120  Make sure you have read and understood the main CONTRIBUTING guide:
   121  
   122  https://github.com/kubernetes/helm/blob/master/CONTRIBUTING.md
   123  
   124  ### Structure of the Code
   125  
   126  The code for the Helm project is organized as follows:
   127  
   128  - The individual programs are located in `cmd/`. Code inside of `cmd/`
   129    is not designed for library re-use.
   130  - Shared libraries are stored in `pkg/`.
   131  - The raw ProtoBuf files are stored in `_proto/hapi` (where `hapi` stands for 
   132    the Helm Application Programming Interface).
   133  - The Go files generated from the `proto` definitions are stored in `pkg/proto`.
   134  - The `scripts/` directory contains a number of utility scripts. Most of these
   135    are used by the CI/CD pipeline.
   136  - The `rootfs/` folder is used for Docker-specific files.
   137  - The `docs/` folder is used for documentation and examples.
   138  
   139  Go dependencies are managed with
   140  [Glide](https://github.com/Masterminds/glide) and stored in the
   141  `vendor/` directory.
   142  
   143  ### Git Conventions
   144  
   145  We use Git for our version control system. The `master` branch is the
   146  home of the current development candidate. Releases are tagged.
   147  
   148  We accept changes to the code via GitHub Pull Requests (PRs). One
   149  workflow for doing this is as follows:
   150  
   151  1. Go to your `$GOPATH/k8s.io` directory and `git clone` the
   152     `github.com/kubernetes/helm` repository.
   153  2. Fork that repository into your GitHub account
   154  3. Add your repository as a remote for `$GOPATH/k8s.io/helm`
   155  4. Create a new working branch (`git checkout -b feat/my-feature`) and
   156     do your work on that branch.
   157  5. When you are ready for us to review, push your branch to GitHub, and
   158     then open a new pull request with us.
   159  
   160  For Git commit messages, we follow the [Semantic Commit Messages](http://karma-runner.github.io/0.13/dev/git-commit-msg.html):
   161  
   162  ```
   163  fix(helm): add --foo flag to 'helm install'
   164  
   165  When 'helm install --foo bar' is run, this will print "foo" in the
   166  output regardless of the outcome of the installation.
   167  
   168  Closes #1234
   169  ```
   170  
   171  Common commit types:
   172  
   173  - fix: Fix a bug or error
   174  - feat: Add a new feature
   175  - docs: Change documentation
   176  - test: Improve testing
   177  - ref: refactor existing code
   178  
   179  Common scopes:
   180  
   181  - helm: The Helm CLI
   182  - tiller: The Tiller server
   183  - proto: Protobuf definitions
   184  - pkg/lint: The lint package. Follow a similar convention for any
   185    package
   186  - `*`: two or more scopes
   187  
   188  Read more:
   189  - The [Deis Guidelines](https://github.com/deis/workflow/blob/master/src/contributing/submitting-a-pull-request.md)
   190    were the inspiration for this section.
   191  - Karma Runner [defines](http://karma-runner.github.io/0.13/dev/git-commit-msg.html) the semantic commit message idea.
   192  
   193  ### Go Conventions
   194  
   195  We follow the Go coding style standards very closely. Typically, running
   196  `go fmt` will make your code beautiful for you.
   197  
   198  We also typically follow the conventions recommended by `go lint` and
   199  `gometalinter`. Run `make test-style` to test the style conformance.
   200  
   201  Read more:
   202  
   203  - Effective Go [introduces formatting](https://golang.org/doc/effective_go.html#formatting).
   204  - The Go Wiki has a great article on [formatting](https://github.com/golang/go/wiki/CodeReviewComments).
   205  
   206  ### Protobuf Conventions
   207  
   208  Because this project is largely Go code, we format our Protobuf files as
   209  closely to Go as possible. There are currently no real formatting rules
   210  or guidelines for Protobuf, but as they emerge, we may opt to follow
   211  those instead.
   212  
   213  Standards:
   214  - Tabs for indentation, not spaces.
   215  - Spacing rules follow Go conventions (curly braces at line end, spaces
   216    around operators).
   217  
   218  Conventions:
   219  - Files should specify their package with `option go_package = "...";`
   220  - Comments should translate into good Go code comments (since `protoc`
   221    copies comments into the destination source code file).
   222  - RPC functions are defined in the same file as their request/response
   223    messages.
   224  - Deprecated RPCs, messages, and fields are marked deprecated in the comments (`// UpdateFoo
   225    DEPRECATED updates a foo.`).