Combine contributing files.
This CL combines the two contributing files from the merge into a single file in CONTRIBUTING.md. BUG=dawn:1356 Change-Id: I863f008f2f842222900b312ce9cc6382d82a32ce Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/86206 Auto-Submit: Dan Sinclair <dsinclair@chromium.org> Reviewed-by: Corentin Wallez <cwallez@chromium.org> Commit-Queue: Corentin Wallez <cwallez@chromium.org>
This commit is contained in:
dan sinclair
Dawn LUCI CQ
parent
668d739adf
commit
d521d0ee40
163
CONTRIBUTING.md
163
CONTRIBUTING.md
|
|
@ -1,5 +1,160 @@
|
|||
See docs/dawn/contributing.md for instructions about how to contribute
|
||||
to Dawn portion of the codebase.
|
||||
# How to contribute
|
||||
|
||||
See docs/tint/contributing.md for instructions about how to contribute
|
||||
to Tint portion of the codebase.
|
||||
First off, we'd love to get your contributions.
|
||||
|
||||
Everything helps other folks using Dawn, Tint and WebGPU: from small fixes and
|
||||
documentation improvements to larger features and optimizations. Please read on
|
||||
to learn about the contribution process.
|
||||
|
||||
## 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.
|
||||
|
||||
## Community Guidelines
|
||||
|
||||
This project follows
|
||||
[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
|
||||
|
||||
## Code reviews
|
||||
|
||||
All submissions, including submissions by project members, require review. We
|
||||
use [Dawn's Gerrit](https://dawn-review.googlesource.com/) for this purpose.
|
||||
|
||||
Any submissions to the [Tint](src/tint) folders should follow the
|
||||
[Tint style guide](docs/tint/style_guide.md).
|
||||
|
||||
|
||||
### Discuss the change if needed
|
||||
|
||||
Some changes are inherently risky, because they have long-term or architectural
|
||||
consequences, contain a lot of unknowns or other reasons. When that's the case
|
||||
it is better to discuss it on the [Dawn Matrix Channel](https://matrix.to/#/#webgpu-dawn:matrix.org)
|
||||
or the [Dawn mailing-list](https://groups.google.com/g/dawn-graphics).
|
||||
|
||||
### Pushing changes to code review
|
||||
|
||||
Before pushing changes to code review, it is better to run `git cl presubmit`
|
||||
that will check the formatting of files and other small things.
|
||||
|
||||
Pushing commits is done with `git push origin HEAD:refs/for/main`. Which means
|
||||
push to `origin` (i.e. Gerrit) the currently checkout out commit to the
|
||||
`refs/for/main` magic branch that creates or updates CLs.
|
||||
|
||||
In the terminal you will see a URL where code review for this CL will happen.
|
||||
CLs start in the "Work In Progress" state. To start the code review proper,
|
||||
click on "Start Review", add reviewers and click "Send and start review". If
|
||||
you are unsure which reviewers to use, pick one of the reviewers in the
|
||||
[Dawn OWNERS file](src/dawn/OWNERS) or [Tint OWNERS file](src/tint/OWNERS)
|
||||
who will review or triage the CL.
|
||||
|
||||
When code review asks for changes in the commits, you can amend them any way
|
||||
you want (small fixup commit and `git rebase -i` are crowd favorites) and run
|
||||
the same `git push origin HEAD:refs/for/main` command.
|
||||
|
||||
### Tracking issues
|
||||
|
||||
We usually like to have commits associated with issues in either
|
||||
[Dawn's issue tracker](https://bugs.chromium.org/p/dawn/issues/list) or
|
||||
[Tint's issue tracker](https://bugs.chromium.org/p/tint/issues/list) so that
|
||||
commits for the issue can all be found on the same page. This is done
|
||||
by adding a `Bug: dawn:<issue number>` or `Bug: tint:<issue number>` tag at the
|
||||
end of the commit message. It is also possible to reference Chromium issues with
|
||||
`Bug: chromium:<issue number>`.
|
||||
|
||||
Some small fixes (like typo fixes, or some one-off maintenance) don't need a
|
||||
tracking issue. When that's the case, it's good practice to call it out by
|
||||
adding a `Bug: None` tag.
|
||||
|
||||
It is possible to make issues fixed automatically when the CL is merged by
|
||||
adding a `Fixed: <project>:<issue number>` tag in the commit message.
|
||||
|
||||
### Iterating on code review
|
||||
|
||||
The project follows the general
|
||||
[Google code review guidelines](https://google.github.io/eng-practices/review/).
|
||||
Most changes need reviews from two committers. Reviewers will set the
|
||||
"Code Review" CR+1 or CR+2 label once the change looks good to them (although
|
||||
it could still have comments that need to be addressed first). When addressing
|
||||
comments, please mark them as "Done" if you just address them, or start a
|
||||
discussion until they are resolved.
|
||||
|
||||
Once you are granted rights (you can ask on your first contribution), you can
|
||||
add the "Commit Queue" CQ+1 label to run the automated tests. Once the
|
||||
CL has CR+2 you can then add the CQ+2 label to run the automated tests and
|
||||
submit the commit if they pass.
|
||||
|
||||
The "Auto Submit" AS+1 label can be used to make Gerrit automatically set the
|
||||
CQ+2 label once the CR+2 label is added.
|
||||
|
||||
## One-time Setup
|
||||
|
||||
The project is setup to use Gerrit in a fashion similar to the Angle project.
|
||||
If you're used to a more Chromium based control flow, see the
|
||||
[Alternate setup](#alternate-setup) section below.
|
||||
|
||||
### Gerrit setup
|
||||
|
||||
Gerrit works a bit differently than Github (if that's what you're used to):
|
||||
there are no forks. Instead everyone works on the same repository. Gerrit has
|
||||
magic branches for various purpose:
|
||||
|
||||
- `refs/for/<branch>` (most commonly `refs/for/main`) is a branch that anyone
|
||||
can push to that will create or update code reviews (called CLs for ChangeList)
|
||||
for the commits pushed.
|
||||
- `refs/changes/00/<change number>/<patchset>` is a branch that corresponds to
|
||||
the commits that were pushed for codereview for "change number" at a certain
|
||||
"patchset" (a new patchset is created each time you push to a CL).
|
||||
|
||||
To create a Gerrit change for review, type:
|
||||
|
||||
```bash
|
||||
git push origin HEAD:refs/for/main
|
||||
```
|
||||
|
||||
#### Gerrit's .gitcookies
|
||||
|
||||
To push commits to Gerrit your `git` command needs to be authenticated. This is
|
||||
done with `.gitcookies` that will make `git` send authentication information
|
||||
when connecting to the remote. To get the `.gitcookies`, log-in to
|
||||
[Dawn's Gerrit](https://dawn-review.googlesource.com) and browse to the
|
||||
[new-password](https://dawn.googlesource.com/new-password) page that will give
|
||||
you shell/cmd commands to run to update `.gitcookie`.
|
||||
|
||||
#### Set up the commit-msg hook
|
||||
|
||||
Gerrit associates commits to CLs based on a `Change-Id:` tag in the commit
|
||||
message. Each push with commits with a `Change-Id:` will update the
|
||||
corresponding CL.
|
||||
|
||||
To add the `commit-msg` hook that will automatically add a `Change-Id:` to your
|
||||
commit messages, run the following command:
|
||||
|
||||
```
|
||||
f=`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
|
||||
```
|
||||
|
||||
Gerrit helpfully reminds you of that command if you forgot to set up the hook
|
||||
before pushing commits.
|
||||
|
||||
### Alternate setup
|
||||
In order to get a more Chromium style workflow there are couple changes need.
|
||||
|
||||
1. Verify there is `.git/hooks/commit-msg` hook setup. (Just moving it to a
|
||||
`commit-msg.bak` will suffice)
|
||||
2. Add `override-squash-uploads = True` to the `gerrit` section of your
|
||||
`.git/config` file
|
||||
|
||||
With those changes, a `Commit-Id` should not be auto-matically appended to your
|
||||
CLs and `git cl upload` needs to be used to push changes to Gerrit. During
|
||||
code review you can commit to your branch as usual, no need to amend.
|
||||
|
||||
This will also allow `git cl status` to work as expected without having to
|
||||
specifically set the issue number for the branch.
|
||||
|
|
|
|||
|
|
@ -1,122 +0,0 @@
|
|||
# How to contribute to Dawn
|
||||
|
||||
First off, we'd love to get your contributions to Dawn!
|
||||
|
||||
Everything helps other folks using Dawn and WebGPU: from small fixes and documentation
|
||||
improvements to larger features and optimizations.
|
||||
Please read on to learn about the contribution process.
|
||||
|
||||
## One time setup
|
||||
|
||||
### 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 Google project), you probably don't need to do
|
||||
it again.
|
||||
|
||||
### Gerrit setup
|
||||
|
||||
Dawn's contributions are submitted and reviewed on [Dawn's Gerrit](https://dawn-review.googlesource.com).
|
||||
|
||||
Gerrit works a bit differently than Github (if that's what you're used to):
|
||||
there are no forks. Instead everyone works on the same repository. Gerrit has
|
||||
magic branches for various purpose:
|
||||
|
||||
- `refs/for/<branch>` (most commonly `refs/for/main`) is a branch that anyone
|
||||
can push to that will create or update code reviews (called CLs for ChangeList)
|
||||
for the commits pushed.
|
||||
- `refs/changes/00/<change number>/<patchset>` is a branch that corresponds to
|
||||
the commits that were pushed for codereview for "change number" at a certain
|
||||
"patchset" (a new patchset is created each time you push to a CL).
|
||||
|
||||
#### Gerrit's .gitcookies
|
||||
|
||||
To push commits to Gerrit your `git` command needs to be authenticated. This is
|
||||
done with `.gitcookies` that will make `git` send authentication information
|
||||
when connecting to the remote. To get the `.gitcookies`, log-in to [Dawn's Gerrit](https://dawn-review.googlesource.com)
|
||||
and browse to the [new-password](https://dawn.googlesource.com/new-password)
|
||||
page that will give you shell/cmd commands to run to update `.gitcookie`.
|
||||
|
||||
#### Set up the commit-msg hook
|
||||
|
||||
Gerrit associates commits to CLs based on a `Change-Id:` tag in the commit
|
||||
message. Each push with commits with a `Change-Id:` will update the
|
||||
corresponding CL.
|
||||
|
||||
To add the `commit-msg` hook that will automatically add a `Change-Id:` to your
|
||||
commit messages, run the following command:
|
||||
|
||||
```
|
||||
f=`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
|
||||
```
|
||||
|
||||
Gerrit helpfully reminds you of that command if you forgot to set up the hook
|
||||
before pushing commits.
|
||||
|
||||
## The code review process
|
||||
|
||||
All submissions, including submissions by project members, require review.
|
||||
|
||||
### Discuss the change if needed
|
||||
|
||||
Some changes are inherently risky, because they have long-term or architectural
|
||||
consequences, contain a lot of unknowns or other reasons. When that's the case
|
||||
it is better to discuss it on the [Dawn Matrix Channel](https://matrix.to/#/#webgpu-dawn:matrix.org)
|
||||
or the [Dawn mailing-list](https://groups.google.com/g/dawn-graphics/members).
|
||||
|
||||
### Pushing changes to code review
|
||||
|
||||
Before pushing changes to code review, it is better to run `git cl presubmit`
|
||||
that will check the formatting of files and other small things.
|
||||
|
||||
Pushing commits is done with `git push origin HEAD:refs/for/main`. Which means
|
||||
push to `origin` (i.e. Gerrit) the currently checkout out commit to the
|
||||
`refs/for/main` magic branch that creates or updates CLs.
|
||||
|
||||
In the terminal you will see a URL where code review for this CL will happen.
|
||||
CLs start in the "Work In Progress" state. To start the code review proper,
|
||||
click on "Start Review", add reviewers and click "Send and start review". If
|
||||
you are unsure which reviewers to use, pick one of the reviewers in the
|
||||
[OWNERS file](../OWNERS) who will review or triage the CL.
|
||||
|
||||
When code review asks for changes in the commits, you can amend them any way
|
||||
you want (small fixup commit and `git rebase -i` are crowd favorites) and run
|
||||
the same `git push origin HEAD:refs/for/main` command.
|
||||
|
||||
### Tracking issues
|
||||
|
||||
We usually like to have commits associated with issues in [Dawn's issue tracker](https://bugs.chromium.org/p/dawn/issues/list)
|
||||
so that commits for the issue can all be found on the same page. This is done
|
||||
by adding a `Bug: dawn:<issue number>` tag at the end of the commit message. It
|
||||
is also possible to reference Chromium or Tint issues with
|
||||
`Bug: tint:<issue number>` or `Bug: chromium:<issue number>`.
|
||||
|
||||
Some small fixes (like typo fixes, or some one-off maintenance) don't need a
|
||||
tracking issue. When that's the case, it's good practice to call it out by
|
||||
adding a `Bug: None` tag.
|
||||
|
||||
It is possible to make issues fixed automatically when the CL is merged by
|
||||
adding a `Fixed: <project>:<issue number>` tag in the commit message.
|
||||
|
||||
### Iterating on code review
|
||||
|
||||
Dawn follows the general [Google code review guidelines](https://google.github.io/eng-practices/review/).
|
||||
Most Dawn changes need reviews from two Dawn committers. Reviewers will set the
|
||||
"Code Review" CR+1 or CR+2 label once the change looks good to them (although
|
||||
it could still have comments that need to be addressed first). When addressing
|
||||
comments, please mark them as "Done" if you just address them, or start a
|
||||
discussion until they are resolved.
|
||||
|
||||
Once you are granted rights (you can ask on your first contribution), you can
|
||||
add the "Commit Queue" CQ+1 label to run the automated tests for Dawn. Once the
|
||||
CL has CR+2 you can then add the CQ+2 label to run the automated tests and
|
||||
submit the commit if they pass.
|
||||
|
||||
The "Auto Submit" AS+1 label can be used to make Gerrit automatically set the
|
||||
CQ+2 label once the CR+2 label is added.
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# How to Contribute
|
||||
|
||||
We'd love to accept your patches and contributions to this project. There are
|
||||
just a few small guidelines you need to follow.
|
||||
|
||||
## 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.
|
||||
|
||||
## Code reviews
|
||||
|
||||
All submissions, including submissions by project members, require review. We
|
||||
use [Dawn's Gerrit](https://dawn-review.googlesource.com/) for this purpose.
|
||||
|
||||
Submissions should follow the [Tint style guide](docs/tint/style_guide.md).
|
||||
|
||||
## Pushing to Gerrit
|
||||
|
||||
Each change requires a `Change-Id` field in the commit message, which is generated by the [Gerrit commit-msg hook](](https://gerrit-review.googlesource.com/Documentation/cmd-hook-commit-msg.html)). \
|
||||
In a bash terminal, with the current path set to your tint source tree, this can be obtained by running the following:
|
||||
|
||||
```bash
|
||||
f=`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
|
||||
```
|
||||
|
||||
If you've already locally committed a change without the `Change-Id`, running `git commit --amend` will add the missing `Change-Id`.
|
||||
|
||||
To create a Gerrit change for review, type:
|
||||
|
||||
```bash
|
||||
git push origin HEAD:refs/for/main
|
||||
```
|
||||
|
||||
## Community Guidelines
|
||||
|
||||
This project follows
|
||||
[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
|
||||
Loading…
Reference in New Issue