github.com/SagerNet/gvisor@v0.0.0-20210707092255-7731c139d75c/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 mod get`. In order to keep the
    36  `WORKSPACE` file in sync, run `tools/go_mod.sh` in place of `go mod`.
    37  
    38  ### Coding Guidelines
    39  
    40  All code should comply with the [style guide](g3doc/style.md). Note that code
    41  may be automatically formatted per the guidelines when merged.
    42  
    43  As a secure runtime, we need to maintain the safety of all of code included in
    44  gVisor. The following rules help mitigate issues.
    45  
    46  Definitions for the rules below:
    47  
    48  `core`:
    49  
    50  *   `//pkg/sentry/...`
    51  *   Transitive dependencies in `//pkg/...`, etc.
    52  
    53  `runsc`:
    54  
    55  *   `//runsc/...`
    56  
    57  Rules:
    58  
    59  *   No cgo in `core` or `runsc`. The final binary must be a statically-linked
    60      pure Go binary.
    61  
    62  *   Any files importing "unsafe" must have a name ending in `_unsafe.go`.
    63  
    64  *   `core` may only depend on the following packages:
    65  
    66      *   Itself.
    67      *   Go standard library.
    68          *   Except (transitively) package "net" (this will result in a non-cgo
    69              binary). Use `//pkg/unet` instead.
    70      *   `@org_golang_x_sys//unix:go_default_library` (Go import
    71          `golang.org/x/sys/unix`).
    72      *   Generated Go protobuf packages.
    73      *   `@org_golang_google_protobuf//proto:go_default_library` (Go import
    74          `google.golang.org/protobuf`).
    75  
    76  *   `runsc` may only depend on the following packages:
    77  
    78      *   All packages allowed for `core`.
    79      *   `@com_github_google_subcommands//:go_default_library` (Go import
    80          `github.com/google/subcommands`).
    81      *   `@com_github_opencontainers_runtime_spec//specs_go:go_default_library`
    82          (Go import `github.com/opencontainers/runtime-spec/specs_go`).
    83  
    84  ### Code reviews
    85  
    86  Before sending code reviews, run `bazel test ...` to ensure tests are passing.
    87  
    88  Code changes are accepted via [pull request][github].
    89  
    90  When approved, the change will be submitted by a team member and automatically
    91  merged into the repository.
    92  
    93  ### Presubmit checks
    94  
    95  Accessing check logs may require membership in the
    96  [gvisor-dev mailing list][gvisor-dev-list], which is public.
    97  
    98  ### Bug IDs
    99  
   100  Some TODOs and NOTEs sprinkled throughout the code have associated IDs of the
   101  form `b/1234`. These correspond to bugs in our internal bug tracker. Eventually
   102  these bugs will be moved to the GitHub Issues, but until then they can simply be
   103  ignored.
   104  
   105  ### Build and test with Docker
   106  
   107  Running `make dev` is a convenient way to build and install `runsc` as a Docker
   108  runtime. The output of this command will show the runtimes installed.
   109  
   110  You may use `make refresh` to refresh the binary after any changes. For example:
   111  
   112  ```bash
   113  make dev
   114  docker run --rm --runtime=my-branch --rm hello-world
   115  make refresh
   116  ```
   117  
   118  ### The small print
   119  
   120  Contributions made by corporations are covered by a different agreement than the
   121  one above, the
   122  [Software Grant and Corporate Contributor License Agreement][gccla].
   123  
   124  [gcla]: https://cla.developers.google.com/about/google-individual
   125  [gccla]: https://cla.developers.google.com/about/google-corporate
   126  [github]: https://github.com/google/gvisor/compare
   127  [gvisor-dev-list]: https://groups.google.com/forum/#!forum/gvisor-dev