Contributing to Tvix

Registration

Self-hosted Gerrit & 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. Do note that our IdP (Keycloak) sometimes has problems doing SSO with GitHub, so you might get an “unexpected error” while trying to sign in with GitHub; that error is not your fault. You can create that account by following these instructions:

1. Checkout TVL’s 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.
4. Commit that generated user entry to our LDAP server configuration in ops/users (for an example, see: CL/2671)
5. If only using LDAP, submit the patch via email (see Submitting changes via 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. 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.

$ 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:

$ 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:

$ 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.

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.

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].