1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
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/
|
