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