diff options
| -rw-r--r-- | tvix/docs/src/SUMMARY.md | 8 | ||||
| -rw-r--r-- | tvix/docs/src/contributing/code-&-commits.md | 76 | ||||
| -rw-r--r-- | tvix/docs/src/contributing/email.md | 33 | ||||
| -rw-r--r-- | tvix/docs/src/contributing/gerrit.md | 112 | ||||
| -rw-r--r-- | tvix/docs/src/getting-started.md | 59 |
5 files changed, 288 insertions, 0 deletions
diff --git a/tvix/docs/src/SUMMARY.md b/tvix/docs/src/SUMMARY.md index 633c13683ebb..6b3c43035bf7 100644 --- a/tvix/docs/src/SUMMARY.md +++ b/tvix/docs/src/SUMMARY.md @@ -1,5 +1,13 @@ # Summary +# Welcome +* [Getting Started](./getting-started.md) + +# Contributing +* [Gerrit](./contributing/gerrit.md) +* [Email](./contributing/email.md) +* [Code & Commits](./contributing/code-&-commits.md) + # Tvix - [Architecture & data flow](./architecture.md) - [TODOs](./TODO.md) diff --git a/tvix/docs/src/contributing/code-&-commits.md b/tvix/docs/src/contributing/code-&-commits.md new file mode 100644 index 000000000000..628c124bf12f --- /dev/null +++ b/tvix/docs/src/contributing/code-&-commits.md @@ -0,0 +1,76 @@ +# Code & Commits + +## Code quality + +This one should go without saying — but please ensure that your code quality +does not fall below the rest of the project. This is of course very subjective, +but as an example if you place code that throws away errors into a block in +which errors are handled properly your change will be rejected. + + +```admonish hint +Usually there is a strong correlation between the visual appearance of a code +block and its quality. This is a simple way to sanity-check your work while +squinting and keeping some distance from your screen ;-) +``` + + +## Commit messages + +The [Angular Conventional Commits][angular] style is the general commit style +used in the Tvix project. Commit messages should be structured like this: + +```admonish example + type(scope): Subject line with at most a 72 character length + + Body of the commit message with an empty line between subject and + body. This text should explain what the change does and why it has + been made, *especially* if it introduces a new feature. + + Relevant issues should be mentioned if they exist. +``` + +Where `type` can be one of: + +* `feat`: A new feature has been introduced +* `fix`: An issue of some kind has been fixed +* `docs`: Documentation or comments have been updated +* `style`: Formatting changes only +* `refactor`: Hopefully self-explanatory! +* `test`: Added missing tests / fixed tests +* `chore`: Maintenance work +* `subtree`: Operations involving `git subtree` + +And `scope` should refer to some kind of logical grouping inside of the +project. + +It does not make sense to include the full path unless it aids in +disambiguating. For example, when changing the struct fields in +`tvix/glue/src/builtins/fetchers.rs` it is enough to write +`refactor(tvix/glue): …`. + +Please take a look at the existing commit log for examples. + + +## Commit content + +Multiple changes should be divided into multiple git commits whenever possible. +Common sense applies. + +The fix for a single-line whitespace issue is fine to include in a different +commit. Introducing a new feature and refactoring (unrelated) code in the same +commit is not fine. + +`git commit -a` is generally **taboo**, whereas on the command line you should +be preferring `git commit -p`. + + +```admonish tip +Tooling can really help this process. The [lazygit][] TUI or [magit][] for +Emacs are worth looking into. +``` + + +[angular]: https://www.conventionalcommits.org/en/ +[lazygit]: https://github.com/jesseduffield/lazygit +[magit]: https://magit.vc diff --git a/tvix/docs/src/contributing/email.md b/tvix/docs/src/contributing/email.md new file mode 100644 index 000000000000..238ff388f595 --- /dev/null +++ b/tvix/docs/src/contributing/email.md @@ -0,0 +1,33 @@ +# Submitting changes via email + +With SSO & local accounts, hopefully Tvix provides you a low-friction or +privacy-respecting way to make contributions by means of +[TVL’s self-hosted Gerrit][gerrit]. However, if you still decide differently, +you may submit a patch via email to `depot@tvl.su` where it will be added to +Gerrit by a contributor. + +Please keep in mind this process is more complicated requiring extra work from +both us & you: + +* You will need to manually check the Gerrit website for updates & someone will + need to relay potential comments to/from Gerrit to you as you won’t get + emails from Gerrit. +* New revisions need to be stewarded by someone uploading changes to Gerrit + on your behalf. +* As CLs cannot change owners, if you decide to get a Gerrit account later on + existing CLs need to be abandoned then recreated. This introduces more churn + to the review process since prior discussion are disconnected. + +Create an appropriate commit locally then 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 inbox][]. + + +[gerrit]: ../contributing/gerrit.html +[public inbox]: https://inbox.tvl.su/depot/ diff --git a/tvix/docs/src/contributing/gerrit.md b/tvix/docs/src/contributing/gerrit.md new file mode 100644 index 000000000000..71877d9d4aab --- /dev/null +++ b/tvix/docs/src/contributing/gerrit.md @@ -0,0 +1,112 @@ +# 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. Do note that our IdP +(Keycloak) sometimes has [problems doing SSO with GitHub][github-problematic], +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][check-out-monorepo] if you haven’t already +2. Be a member of `#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 +[github-problematic]: https://b.tvl.fyi/issues/201 +[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` diff --git a/tvix/docs/src/getting-started.md b/tvix/docs/src/getting-started.md new file mode 100644 index 000000000000..1cbb6de7d4f7 --- /dev/null +++ b/tvix/docs/src/getting-started.md @@ -0,0 +1,59 @@ +# Getting Started + +## Getting the code, a developer shell, & building the CLI + +Tvix can be built with the Rust standard `cargo build`. A Nix shell is provided +with the correctly-versioned tooling to build. + +### TVL monorepo + +```console +$ git clone https://code.tvl.fyi/depot.git +$ cd depot +``` + +[Direnv][] is highly recommended in order to enable [`mg`][mg], a tool for +workflows in monorepos. Follow the [Direnv installation +instructions][direnv-inst], then after it’s set up continue with: + +```console +$ direnv allow +$ mg shell //tvix:shell +$ cd tvix +$ cargo build +``` + +### Or just Tvix + +At present, this option isn’t suitable for contributions & lacks the tooling of +the monorepo, but still provides a `shell.nix` which can be used for building +the Tvix project. + +```console +$ git clone https://code.tvl.fyi/depot.git:workspace=views/tvix.git +$ cd tvix +$ nix-shell +$ cargo build +``` + + +# Builds & tests + +All projects are built using [Nix][] to avoid ‘build pollution’ via the user’s +local environment. + +If you have Nix installed and are contributing to a project tracked in this +repository, you can usually build the project by calling `nix-build -A +path.to.project`. + +For example, to build a project located at `//tools/foo` you would call +`nix-build -A tools.foo` + +If the project has tests, check that they still work before submitting your +change. + + +[Direnv]: https://direnv.net +[direnv-inst]: https://direnv.net/docs/installation.html +[Nix]: https://nixos.org/nix/ +[mg]: https://code.tvl.fyi/tree/tools/magrathea |