docs(REVIEWS): Add documentation for code reviews in Gerrit
Adds a document with information about the review process, how to get an account, how to submit patches via email and so on. Change-Id: I7c266e063ef53ab6aa79dd2582bc0e4fa8dcf5c0 Reviewed-on: https://cl.tvl.fyi/c/depot/+/446 Reviewed-by: riking <rikingcoding@gmail.com>
This commit is contained in:
Vincent Ambo
tazjin
parent
5e5e02d6a7
commit
b27239b60a
2 changed files with 133 additions and 11 deletions
|
|
@ -10,6 +10,7 @@ Contribution Guidelines
|
||||||
- [Commit content](#commit-content)
|
- [Commit content](#commit-content)
|
||||||
- [Code quality](#code-quality)
|
- [Code quality](#code-quality)
|
||||||
- [Builds & tests](#builds--tests)
|
- [Builds & tests](#builds--tests)
|
||||||
|
- [Submitting changes](#submitting-changes)
|
||||||
|
|
||||||
<!-- markdown-toc end -->
|
<!-- markdown-toc end -->
|
||||||
|
|
||||||
|
|
@ -110,17 +111,9 @@ change.
|
||||||
|
|
||||||
## Submitting changes
|
## Submitting changes
|
||||||
|
|
||||||
Development is primarily tracked at [cl.tvl.fyi](https://cl.tvl.fyi) using
|
The code review & change submission process is described in the [code
|
||||||
Gerrit. If you have an account, use the standard Gerrit workflows to submit a
|
review][] documentation.
|
||||||
change.
|
|
||||||
|
|
||||||
If you do not have an account, you can alternatively submit a patch
|
|
||||||
via email. Create an appropriate commit locally and send it to
|
|
||||||
`depot@tazj.in` using either `git send-email` or `git format-patch`.
|
|
||||||
The email address is a [public group][].
|
|
||||||
|
|
||||||
Patches submitted via email will be added to Gerrit by a contributor.
|
|
||||||
|
|
||||||
[magit]: https://magit.vc/
|
[magit]: https://magit.vc/
|
||||||
[Nix]: https://nixos.org/nix/
|
[Nix]: https://nixos.org/nix/
|
||||||
[public group]: https://groups.google.com/a/tazj.in/forum/?hl=en#!forum/depot
|
[code review]: ./REVIEWS.md
|
||||||
|
|
|
||||||
129
docs/REVIEWS.md
Normal file
129
docs/REVIEWS.md
Normal file
|
|
@ -0,0 +1,129 @@
|
||||||
|
TVL Code Reviews
|
||||||
|
================
|
||||||
|
|
||||||
|
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
|
||||||
|
**Table of Contents**
|
||||||
|
|
||||||
|
- [TVL Code Reviews](#tvl-code-reviews)
|
||||||
|
- [Gerrit setup](#gerrit-setup)
|
||||||
|
- [Gerrit workflows](#gerrit-workflows)
|
||||||
|
- [Review process & approvals](#review-process--approvals)
|
||||||
|
- [Registration](#registration)
|
||||||
|
- [Submitting changes via email](#submitting-changes-via-email)
|
||||||
|
|
||||||
|
<!-- markdown-toc end -->
|
||||||
|
|
||||||
|
|
||||||
|
This document describes the TVL code review process & tooling. If you are
|
||||||
|
looking for general contribution guidelines, please look at the [general
|
||||||
|
contribution guidelines](./CONTRIBUTING.md).
|
||||||
|
|
||||||
|
All changes are tracked at [cl.tvl.fyi](https://cl.tvl.fyi) using Gerrit. See
|
||||||
|
[Registration](#registration) for information on how to register an account.
|
||||||
|
|
||||||
|
## Gerrit setup
|
||||||
|
|
||||||
|
Gerrit uses the concept of change IDs to track commits across rebases and other
|
||||||
|
operations that might change their hashes, and link them to unique changes in
|
||||||
|
Gerrit.
|
||||||
|
|
||||||
|
To make this process smooth for users, the repository should be cloned and a
|
||||||
|
commit hook should be installed as follows:
|
||||||
|
|
||||||
|
```
|
||||||
|
git clone "ssh://$USER@code.tvl.fyi:29418/depot"
|
||||||
|
scp -p -P 29418 $USER@code.tvl.fyi:hooks/commit-msg "depot/.git/hooks/"
|
||||||
|
```
|
||||||
|
|
||||||
|
If you have a previous clone of the depot via HTTP you can use `git remote
|
||||||
|
set-url` to update the origin URL and install the hook in the same way as above.
|
||||||
|
|
||||||
|
## Gerrit workflows
|
||||||
|
|
||||||
|
The developer workflow on Gerrit is quite different from what GitHub-users are
|
||||||
|
used to.
|
||||||
|
|
||||||
|
The depot does not have branches (other than Gerrit's internal metadata refs)
|
||||||
|
and all development happens at `HEAD`.
|
||||||
|
|
||||||
|
Every time you create a new commit the change hook will insert a unique
|
||||||
|
`Change-Id` tag into the commit message. Once you are satisfied with the state
|
||||||
|
of your commit and want to submit it for review, you push it to a git ref called
|
||||||
|
`refs/for/master`. This designates the commits as changelists (CLs) targeted for
|
||||||
|
the `master` branch.
|
||||||
|
|
||||||
|
```
|
||||||
|
Example:
|
||||||
|
git commit -m 'docs(REVIEWS): Fixed all the errors in the reviews docs'
|
||||||
|
git push origin HEAD:refs/for/master
|
||||||
|
```
|
||||||
|
|
||||||
|
TIP: Every individual commit will become a separate change. We do not merge
|
||||||
|
related commits, but instead submit them one by one. Be aware that if you are
|
||||||
|
expecting a different behaviour and attempt something like an unsquashed subtree
|
||||||
|
merge, you will produce a *lot* of CLs. This is strongly discouraged.
|
||||||
|
|
||||||
|
During your review, the reviewer(s) might ask you to make changes. You can
|
||||||
|
simply amend your commit(s) and push to the same ref. Gerrit will automatically
|
||||||
|
update your changes.
|
||||||
|
|
||||||
|
Read more about the Gerrit workflow in the [Gerrit walkthrough][].
|
||||||
|
|
||||||
|
## Review process & approvals
|
||||||
|
|
||||||
|
Each user has the ability to create their own users directory in
|
||||||
|
`//users/<username>` in which they can submit code without review from other
|
||||||
|
contributors (they will still need to +2 their own changes, and the initial
|
||||||
|
check-in of the `OWNERS` file needs to be reviewed).
|
||||||
|
|
||||||
|
You can set a directory like this up for yourself by proposing a change similar
|
||||||
|
to [CL/246](https://cl.tvl.fyi/c/depot/+/246).
|
||||||
|
|
||||||
|
For all paths outside of `//users`, code review is required. We have no strict
|
||||||
|
guidelines about the review process itself, as we're not a megacorp, but we have
|
||||||
|
formalised checks before submitting:
|
||||||
|
|
||||||
|
* At least one person who is [an owner][OWNERS] of the codepath must have given
|
||||||
|
a +2 review
|
||||||
|
* The commit message must conform to our [guidelines][]
|
||||||
|
* No code review comments must be left unresolved
|
||||||
|
|
||||||
|
If all these conditions are fulfilled, the **change author submits their change
|
||||||
|
themselves**.
|
||||||
|
|
||||||
|
## Registration
|
||||||
|
|
||||||
|
If you would like to have an account on the Gerrit instance, follow these
|
||||||
|
instructions:
|
||||||
|
|
||||||
|
1. Be a member of `##tvl`.
|
||||||
|
2. Clone the depot locally.
|
||||||
|
3. Create a user entry in our LDAP server, in [`contents.ldif`][]. You create
|
||||||
|
your password hash by using `slappasswd`, which ships in the `openldap`
|
||||||
|
package on most distributions.
|
||||||
|
|
||||||
|
On systems with Nix systems you can use `nix-shell -p openldap` to get access
|
||||||
|
to the command.
|
||||||
|
4. Create a commit adding yourself (see e.g.
|
||||||
|
[CL/223](https://cl.tvl.fyi/c/depot/+/223)).
|
||||||
|
5. Submit the commit via email (see below).
|
||||||
|
|
||||||
|
## Submitting changes via email
|
||||||
|
|
||||||
|
You can submit a patch via email to `depot@tazj.in` and it will be added to
|
||||||
|
Gerrit by a contributor.
|
||||||
|
|
||||||
|
Create an appropriate commit locally and send it us using either of these options:
|
||||||
|
|
||||||
|
* `git format-patch`: This will create a `.patch` file which you should email to
|
||||||
|
us.
|
||||||
|
* `git send-email`: If configured on your system, this will take care of the
|
||||||
|
whole emailing process for you.
|
||||||
|
|
||||||
|
The email address is a [public group][].
|
||||||
|
|
||||||
|
[Gerrit walkthrough]: https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough.html
|
||||||
|
[OWNERS]: https://cl.tvl.fyi/plugins/owners/Documentation/config.md
|
||||||
|
[guidelines]: ./CONTRIBUTING.md#commit-messages
|
||||||
|
[`contents.ldif`]: https://code.tvl.fyi/tree/ops/nixos/tvl-slapd/contents.ldif
|
||||||
|
[public group]: https://groups.google.com/a/tazj.in/forum/?hl=en#!forum/depot
|
||||||
Loading…
Reference in a new issue