c60f4ccfda
This should be fixed with the switch to a "GitHub App" for authentication. Change-Id: I0bd8b4b9c9f53a754a12ce07f193d19f61f56014 Reviewed-on: https://cl.tvl.fyi/c/depot/+/12414 Reviewed-by: Ilan Joselevich <personal@ilanjoselevich.com> Tested-by: BuildkiteCI Autosubmit: flokli <flokli@flokli.de>
110 lines
4.5 KiB
Markdown
110 lines
4.5 KiB
Markdown
# Contributing to Tvix
|
||
|
||
## Registration
|
||
|
||
Self-hosted [Gerrit](https://www.gerritcodereview.com) & changelists (CLs) are
|
||
the preferred method of contributions & review.
|
||
|
||
TVL’s Gerrit supports single sign-on (SSO) using a GitHub, GitLab, or
|
||
StackOverflow account.
|
||
|
||
Additionally if you would prefer not to use an SSO option or wish to have a
|
||
backup authentication strategy in the event of downed server or otherwise, we
|
||
recommend setting up a TVL-specific LDAP account.
|
||
|
||
You can create such an account by following these instructions:
|
||
|
||
1. Checkout [TVL’s monorepo][check-out-monorepo] if you haven’t already
|
||
2. Be a member of `#tvix-dev` (and/or `#tvl`) on [hackint][], a communication
|
||
network.
|
||
3. Generate a user entry using [//web/pwcrypt](https://signup.tvl.fyi/).
|
||
4. Commit that generated user entry to our LDAP server configuration in
|
||
[ops/users][ops-users] (for an example, see:
|
||
[CL/2671](https://cl.tvl.fyi/c/depot/+/2671))
|
||
5. If only using LDAP, submit the patch via email (see [<cite>Submitting
|
||
changes via email</cite>][email])
|
||
|
||
|
||
## 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.
|
||
|
||
First, [upload your public SSH keys to Gerrit][Gerrit SSH]. Then change your
|
||
remote to point to your newly-registered user over SSH. Then follow up with Git
|
||
config by setting the default push URLs for & installing commit hooks for a
|
||
smoother Gerrit experience.
|
||
|
||
```console
|
||
$ cd depot
|
||
$ git remote set-url origin "ssh://$USER@code.tvl.fyi:29418/depot"
|
||
$ git config remote.origin.url "ssh://$USER@code.tvl.fyi:29418/depot"
|
||
$ git config remote.origin.push "HEAD:refs/for/canon"
|
||
$ curl -L --compressed https://cl.tvl.fyi/tools/hooks/commit-msg | tee .git/hooks/commit-msg
|
||
…
|
||
if ! mv "${dest}" "$1" ; then
|
||
echo "cannot mv ${dest} to $1"
|
||
exit 1
|
||
fi
|
||
$ chmod +x .git/hooks/commit-msg
|
||
```
|
||
|
||
## Gerrit workflow
|
||
|
||
The workflow on Gerrit is quite different than the pull request (PR) model that
|
||
many developers are more likely to be accustomed to. Instead of pushing changes
|
||
to remote branches, all changes have to be pushed to `refs/for/canon`. For each
|
||
commit that is pushed there, a change request is created automatically
|
||
|
||
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/canon`. This designates the commits as changelists (CLs)
|
||
targeted for the `canon` branch.
|
||
|
||
After you feel satisfied with your changes changes, push to the default:
|
||
|
||
```console
|
||
$ git commit -m 'docs(REVIEWS): Fixed all the errors in the reviews docs'
|
||
$ git push origin
|
||
```
|
||
|
||
Or to a special target, such as a work-in-progress CL:
|
||
|
||
```console
|
||
$ git push origin HEAD:refs/for/canon%wip
|
||
```
|
||
|
||
During the review process, the reviewer(s) might ask you to make changes. You
|
||
can simply amend[^amend] your commit(s) then push to the same ref (`--force*`
|
||
flags not needed). Gerrit will automatically update your changes.
|
||
|
||
```admonish caution
|
||
Every individual commit will become a separate change. We do *not* squash
|
||
related commits, but instead submit them one by one. Be aware that if you are
|
||
expecting a different behavior such as attempt something like an unsquashed
|
||
subtree merge, you will produce a *lot* of CLs. This is strongly discouraged.
|
||
```
|
||
|
||
```admonish tip
|
||
If do not have experience with the Gerrit model, consider reading the
|
||
[<cite>Working with Gerrit: An example</cite>][Gerrit Walkthrough] or
|
||
[<cite>Basic Gerrit Walkthrough — For GitHub Users</cite>][github-diff].
|
||
|
||
It will also be important to read about [attention sets][] to understand how
|
||
your ‘turn’ works, how notifications will be distributed to users through the
|
||
system, as well as the other [attention set rules][attention-set-rules].
|
||
```
|
||
|
||
|
||
[check-out-monorepo]: ./getting-started#tvl-monorepo
|
||
[email]: ../contributing/email.html
|
||
[Gerrit SSH]: https://cl.tvl.fyi/settings/#SSHKeys
|
||
[Gerrit walkthrough]: https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough.html
|
||
[ops-users]: https://code.tvl.fyi/tree/ops/users/default.nix
|
||
[hackint]: https://hackint.org
|
||
[github-diff]: https://gerrit.wikimedia.org/r/Documentation/intro-gerrit-walkthrough-github.html
|
||
[attention sets]: https://gerrit-review.googlesource.com/Documentation/user-attention-set.html
|
||
[attention-set-rules]: https://gerrit-review.googlesource.com/Documentation/user-attention-set.html#_rules
|
||
[^keycloak]: [^amend]: `git commit --amend`
|