blob: fb78b53de3b1a1f9db4b21b4adf2c4145f63ae9a [file] [log] [blame] [view]
dan sinclaird521d0e2022-04-10 22:14:00 +00001# How to contribute
Dan Sinclair6e581892020-03-02 15:47:43 -05002
dan sinclaird521d0e2022-04-10 22:14:00 +00003First off, we'd love to get your contributions.
4
5Everything helps other folks using Dawn, Tint and WebGPU: from small fixes and
6documentation improvements to larger features and optimizations. Please read on
7to learn about the contribution process.
8
9## Contributor License Agreement
10
11Contributions to this project must be accompanied by a Contributor License
12Agreement. You (or your employer) retain the copyright to your contribution;
13this simply gives us permission to use and redistribute your contributions as
14part of the project. Head over to <https://cla.developers.google.com/> to see
15your current agreements on file or to sign a new one.
16
17You generally only need to submit a CLA once, so if you've already submitted one
18(even if it was for a different project), you probably don't need to do it
19again.
20
21## Community Guidelines
22
23This project follows
24[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
25
26## Code reviews
27
28All submissions, including submissions by project members, require review. We
29use [Dawn's Gerrit](https://dawn-review.googlesource.com/) for this purpose.
30
31Any submissions to the [Tint](src/tint) folders should follow the
32[Tint style guide](docs/tint/style_guide.md).
33
34
35### Discuss the change if needed
36
37Some changes are inherently risky, because they have long-term or architectural
38consequences, contain a lot of unknowns or other reasons. When that's the case
39it is better to discuss it on the [Dawn Matrix Channel](https://matrix.to/#/#webgpu-dawn:matrix.org)
40or the [Dawn mailing-list](https://groups.google.com/g/dawn-graphics).
41
42### Pushing changes to code review
43
44Before pushing changes to code review, it is better to run `git cl presubmit`
45that will check the formatting of files and other small things.
46
47Pushing commits is done with `git push origin HEAD:refs/for/main`. Which means
48push to `origin` (i.e. Gerrit) the currently checkout out commit to the
49`refs/for/main` magic branch that creates or updates CLs.
50
51In the terminal you will see a URL where code review for this CL will happen.
52CLs start in the "Work In Progress" state. To start the code review proper,
53click on "Start Review", add reviewers and click "Send and start review". If
54you are unsure which reviewers to use, pick one of the reviewers in the
55[Dawn OWNERS file](src/dawn/OWNERS) or [Tint OWNERS file](src/tint/OWNERS)
56who will review or triage the CL.
57
58When code review asks for changes in the commits, you can amend them any way
59you want (small fixup commit and `git rebase -i` are crowd favorites) and run
60the same `git push origin HEAD:refs/for/main` command.
61
62### Tracking issues
63
64We usually like to have commits associated with issues in either
65[Dawn's issue tracker](https://bugs.chromium.org/p/dawn/issues/list) or
66[Tint's issue tracker](https://bugs.chromium.org/p/tint/issues/list) so that
67commits for the issue can all be found on the same page. This is done
68by adding a `Bug: dawn:<issue number>` or `Bug: tint:<issue number>` tag at the
69end of the commit message. It is also possible to reference Chromium issues with
70`Bug: chromium:<issue number>`.
71
72Some small fixes (like typo fixes, or some one-off maintenance) don't need a
73tracking issue. When that's the case, it's good practice to call it out by
74adding a `Bug: None` tag.
75
76It is possible to make issues fixed automatically when the CL is merged by
77adding a `Fixed: <project>:<issue number>` tag in the commit message.
78
79### Iterating on code review
80
81The project follows the general
82[Google code review guidelines](https://google.github.io/eng-practices/review/).
83Most changes need reviews from two committers. Reviewers will set the
84"Code Review" CR+1 or CR+2 label once the change looks good to them (although
85it could still have comments that need to be addressed first). When addressing
86comments, please mark them as "Done" if you just address them, or start a
87discussion until they are resolved.
88
89Once you are granted rights (you can ask on your first contribution), you can
90add the "Commit Queue" CQ+1 label to run the automated tests. Once the
91CL has CR+2 you can then add the CQ+2 label to run the automated tests and
92submit the commit if they pass.
93
94The "Auto Submit" AS+1 label can be used to make Gerrit automatically set the
95CQ+2 label once the CR+2 label is added.
96
97## One-time Setup
98
99The project is setup to use Gerrit in a fashion similar to the Angle project.
100If you're used to a more Chromium based control flow, see the
101[Alternate setup](#alternate-setup) section below.
102
103### Gerrit setup
104
105Gerrit works a bit differently than Github (if that's what you're used to):
106there are no forks. Instead everyone works on the same repository. Gerrit has
107magic branches for various purpose:
108
109 - `refs/for/<branch>` (most commonly `refs/for/main`) is a branch that anyone
110can push to that will create or update code reviews (called CLs for ChangeList)
111for the commits pushed.
112 - `refs/changes/00/<change number>/<patchset>` is a branch that corresponds to
113the commits that were pushed for codereview for "change number" at a certain
114"patchset" (a new patchset is created each time you push to a CL).
115
116To create a Gerrit change for review, type:
117
118```bash
119git push origin HEAD:refs/for/main
120```
121
122#### Gerrit's .gitcookies
123
124To push commits to Gerrit your `git` command needs to be authenticated. This is
125done with `.gitcookies` that will make `git` send authentication information
126when connecting to the remote. To get the `.gitcookies`, log-in to
127[Dawn's Gerrit](https://dawn-review.googlesource.com) and browse to the
128[new-password](https://dawn.googlesource.com/new-password) page that will give
129you shell/cmd commands to run to update `.gitcookie`.
130
131#### Set up the commit-msg hook
132
133Gerrit associates commits to CLs based on a `Change-Id:` tag in the commit
134message. Each push with commits with a `Change-Id:` will update the
135corresponding CL.
136
137To add the `commit-msg` hook that will automatically add a `Change-Id:` to your
138commit messages, run the following command:
139
140```
141f=`git rev-parse --git-dir`/hooks/commit-msg ; mkdir -p $(dirname $f) ; curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x $f
142```
143
144Gerrit helpfully reminds you of that command if you forgot to set up the hook
145before pushing commits.
146
147### Alternate setup
148In order to get a more Chromium style workflow there are couple changes need.
149
1501. Verify there is `.git/hooks/commit-msg` hook setup. (Just moving it to a
151 `commit-msg.bak` will suffice)
1522. Add `override-squash-uploads = True` to the `gerrit` section of your
153 `.git/config` file
154
155With those changes, a `Commit-Id` should not be auto-matically appended to your
156CLs and `git cl upload` needs to be used to push changes to Gerrit. During
157code review you can commit to your branch as usual, no need to amend.
158
159This will also allow `git cl status` to work as expected without having to
160specifically set the issue number for the branch.