gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/CONTRIBUTING.md (about)

     1  # Contributing
     2  
     3  Want to contribute? Great! First, read this page.
     4  
     5  ### Contributor License Agreement
     6  
     7  Contributions to this project must be accompanied by a Contributor License
     8  Agreement. You (or your employer) retain the copyright to your contribution;
     9  this simply gives us permission to use and redistribute your contributions as
    10  part of the project. Head over to <https://cla.developers.google.com/> to see
    11  your current agreements on file or to sign a new one.
    12  
    13  You generally only need to submit a CLA once, so if you've already submitted one
    14  (even if it was for a different project), you probably don't need to do it
    15  again.
    16  
    17  ### Using GOPATH
    18  
    19  Some editors may require the code to be structured in a `GOPATH` directory tree.
    20  In this case, you may use the `:gopath` target to generate a directory tree with
    21  symlinks to the original source files.
    22  
    23  ```
    24  bazel build :gopath
    25  ```
    26  
    27  You can then set the `GOPATH` in your editor to `bazel-bin/gopath`.
    28  
    29  If you use this mechanism, keep in mind that the generated tree is not the
    30  canonical source. You will still need to build and test with `bazel`. New files
    31  will need to be added to the appropriate `BUILD` files, and the `:gopath` target
    32  will need to be re-run to generate appropriate symlinks in the `GOPATH`
    33  directory tree.
    34  
    35  Dependencies can be added by using `go get`. In order to keep the `WORKSPACE`
    36  file in sync, run `bazel run //:gazelle -- update-repos -from_file=go.mod` in
    37  place of `go mod`.
    38  
    39  ### Coding Guidelines
    40  
    41  All code should comply with the [style guide](g3doc/style.md). Note that code
    42  may be automatically formatted per the guidelines when merged.
    43  
    44  As a secure runtime, we need to maintain the safety of all of code included in
    45  gVisor. The following rules help mitigate issues.
    46  
    47  Definitions for the rules below:
    48  
    49  `core`:
    50  
    51  *   `//pkg/sentry/...`
    52  *   Transitive dependencies in `//pkg/...`, etc.
    53  
    54  `runsc`:
    55  
    56  *   `//runsc/...`
    57  
    58  Rules:
    59  
    60  *   No cgo in `core` or `runsc`. The final binary must be a statically-linked
    61      pure Go binary.
    62  
    63  *   Any files importing "unsafe" must have a name ending in `_unsafe.go`.
    64  
    65  *   `core` may only depend on the following packages:
    66  
    67      *   Itself.
    68      *   Go standard library.
    69      *   `@org_golang_x_sys//unix:go_default_library` (Go import
    70          `golang.org/x/sys/unix`).
    71      *   `@org_golang_x_time//rate:go_default_library` (Go import
    72          `golang.org/x/time/rate`).
    73      *   `@com_github_google_btree//:go_default_library"` (Go import
    74          `github.com/google/btree`).
    75      *   Generated Go protobuf packages.
    76      *   `@org_golang_google_protobuf//proto:go_default_library` (Go import
    77          `google.golang.org/protobuf`).
    78  
    79  *   `runsc` may only depend on the following packages:
    80  
    81      *   All packages allowed for `core`.
    82      *   `@com_github_google_subcommands//:go_default_library` (Go import
    83          `github.com/google/subcommands`).
    84      *   `@com_github_opencontainers_runtime_spec//specs_go:go_default_library`
    85          (Go import `github.com/opencontainers/runtime-spec/specs_go`).
    86  
    87  *   For performance reasons, `runsc boot` may not run the `netpoller` goroutine.
    88  
    89  ### Code reviews
    90  
    91  Before sending code reviews, run `bazel test ...` to ensure tests are passing.
    92  
    93  Code changes are accepted via [pull request][github].
    94  
    95  When approved, the change will be submitted by a team member and automatically
    96  merged into the repository.
    97  
    98  ### Presubmit checks
    99  
   100  Accessing check logs may require membership in the
   101  [gvisor-dev mailing list][gvisor-dev-list], which is public.
   102  
   103  ### Bug IDs
   104  
   105  Some TODOs and NOTEs sprinkled throughout the code have associated IDs of the
   106  form `b/1234`. These correspond to bugs in our internal bug tracker. Eventually
   107  these bugs will be moved to the GitHub Issues, but until then they can simply be
   108  ignored.
   109  
   110  ### Build and test with Docker
   111  
   112  Running `make dev` is a convenient way to build and install `runsc` as a Docker
   113  runtime. The output of this command will show the runtimes installed.
   114  
   115  You may use `make refresh` to refresh the binary after any changes. For example:
   116  
   117  ```bash
   118  make dev
   119  docker run --rm --runtime=my-branch --rm hello-world
   120  make refresh
   121  ```
   122  
   123  ### Update golang dependencies
   124  
   125  First, we need to update dependencies in the go.mod and go.sum files. To do
   126  that, we should checkout the go branch and update dependencies using the go get
   127  tool.
   128  
   129  ```bash
   130  git checkout origin/go
   131  go get golang.org/x/net
   132  ```
   133  
   134  Next, we should checkout the master branch and update dependencies in the
   135  WORKSPACE file using the Gazelle tool.
   136  
   137  ```bash
   138  git checkout origin/master
   139  bazel run //:gazelle -- update-repos -from_file=go.mod
   140  ```
   141  
   142  ### The small print
   143  
   144  Contributions made by corporations are covered by a different agreement than the
   145  one above, the
   146  [Software Grant and Corporate Contributor License Agreement][gccla].
   147  
   148  [gcla]: https://cla.developers.google.com/about/google-individual
   149  [gccla]: https://cla.developers.google.com/about/google-corporate
   150  [github]: https://github.com/google/gvisor/compare
   151  [gvisor-dev-list]: https://groups.google.com/forum/#!forum/gvisor-dev