Want to contribute? Great! First, read this page.

### 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
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.

### Using GOPATH

Some editors may require the code to be structured in a `GOPATH` directory tree.
In this case, you may use the `:gopath` target to generate a directory tree with
symlinks to the original source files.

```
bazel build :gopath
```

You can then set the `GOPATH` in your editor to `bazel-bin/gopath`.

If you use this mechanism, keep in mind that the generated tree is not the
canonical source. You will still need to build and test with `bazel`. New files
will need to be added to the appropriate `BUILD` files, and the `:gopath` target
will need to be re-run to generate appropriate symlinks in the `GOPATH`
directory tree.

### Coding Guidelines

All Go code should conform to the [Go style guidelines][gostyle]. C++ code
should conform to the [Google C++ Style Guide][cppstyle] and the guidelines
described for [tests][teststyle].

As a secure runtime, we need to maintain the safety of all of code included in
gVisor. The following rules help mitigate issues.

Definitions for the rules below:

`core`:

*   `//pkg/sentry/...`
*   Transitive dependencies in `//pkg/...`, `//third_party/...`.

`runsc`:

*   `//runsc/...`

Rules:

*   No cgo in `core` or `runsc`. The final binary must be a statically-linked
    pure Go binary.

*   Any files importing "unsafe" must have a name ending in `_unsafe.go`.

*   `core` may only depend on the following packages:

    *   Itself.
    *   Go standard library.
        *   Except (transitively) package "net" (this will result in a non-cgo
            binary). Use `//pkg/unet` instead.
    *   `@org_golang_x_sys//unix:go_default_library` (Go import
        `golang.org/x/sys/unix`).
    *   Generated Go protobuf packages.
    *   `@com_github_golang_protobuf//proto:go_default_library` (Go import
        `github.com/golang/protobuf/proto`).
    *   `@com_github_golang_protobuf//ptypes:go_default_library` (Go import
        `github.com/golang/protobuf/ptypes`).

*   `runsc` may only depend on the following packages:

    *   All packages allowed for `core`.
    *   `@com_github_google_subcommands//:go_default_library` (Go import
        `github.com/google/subcommands`).
    *   `@com_github_opencontainers_runtime_spec//specs_go:go_default_library`
        (Go import `github.com/opencontainers/runtime-spec/specs_go`).

### Code reviews

All changes must be submitted via [Gerrit][gerrit].

All submissions, including submissions by project members, require review.

To submit a patch, first clone the canonical repository.

```
git clone https://gvisor.googlesource.com/gvisor
```

From within the cloned directory, install the commit hooks (optional, but if you
don't you will need to generate Change-Ids manually in your commits).

```
curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit-review.googlesource.com/tools/hooks/commit-msg
chmod +x `git rev-parse --git-dir`/hooks/commit-msg
```

Edit the source and generate commits as you normally would. While making
changes, remember to organize commits logically. Changes are not reviewed per
branch (as with a pull request), they are reviewed per commit.

Before posting a new patch, you will need to generate an appropriate
authentication cookie. Visit the [repository][repo] and click the "Generate
Password" link at the top of the page for instructions.

To post a patch for review, push to a special "for" reference.

```
git push origin HEAD:refs/for/master
```

A change link will be generated for the commit, and a team member will review
your change request, provide feedback (and submit when appropriate).

If you receive an error like `No Contributor Agreement on file for user ...`,
make sure you've [signed the CLA](#contributor-license-agreement).

To address feedback, you may need to amend your commit and repush (don't change
the Commit-Id in the commit message). This will generate a new version of the
change.

When approved, the change will be submitted by a team member and automatically
merged into the repository.

### Bug IDs

Some TODOs and NOTEs sprinkled throughout the code have associated IDs of the
form b/1234. These correspond to bugs in our internal bug tracker. Eventually
these bugs will be moved to the GitHub Issues, but until then they can simply be
ignored.

### The small print

Contributions made by corporations are covered by a different agreement than the
one above, the
[Software Grant and Corporate Contributor License Agreement][gccla].

[cppstyle]: https://google.github.io/styleguide/cppguide.html
[gcla]: https://cla.developers.google.com/about/google-individual
[gccla]: https://cla.developers.google.com/about/google-corporate
[gerrit]: https://gvisor-review.googlesource.com
[gostyle]: https://github.com/golang/go/wiki/CodeReviewComments
[repo]: https://gvisor.googlesource.com
[teststyle]: ./test/