26959ce094
Change-Id: If657f4b49d16260b35f13a4124caa336bbe3124b Reviewed-on: https://cl.tvl.fyi/c/depot/+/449 Reviewed-by: riking <rikingcoding@gmail.com>
129 lines
4.9 KiB
Markdown
129 lines
4.9 KiB
Markdown
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 [tvl-slapd/default.nix][tvl-slapd].
|
|
You can 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
|
|
[tvl-slapd]: https://code.tvl.fyi/tree/ops/nixos/tvl-slapd/default.nix
|
|
[public group]: https://groups.google.com/a/tazj.in/forum/?hl=en#!forum/depot
|