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