diff --git a/snix/docs/src/SUMMARY.md b/snix/docs/src/SUMMARY.md index eb414c405..49cc8654c 100644 --- a/snix/docs/src/SUMMARY.md +++ b/snix/docs/src/SUMMARY.md @@ -4,11 +4,6 @@ * [Introduction](./introduction.md) * [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/snix/docs/src/contributing/code-&-commits.md b/snix/docs/src/contributing/code-&-commits.md deleted file mode 100644 index 628c124bf..000000000 --- a/snix/docs/src/contributing/code-&-commits.md +++ /dev/null @@ -1,76 +0,0 @@ -# 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/snix/docs/src/contributing/email.md b/snix/docs/src/contributing/email.md deleted file mode 100644 index 238ff388f..000000000 --- a/snix/docs/src/contributing/email.md +++ /dev/null @@ -1,33 +0,0 @@ -# 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/snix/docs/src/contributing/gerrit.md b/snix/docs/src/contributing/gerrit.md deleted file mode 100644 index 3644e8cb0..000000000 --- a/snix/docs/src/contributing/gerrit.md +++ /dev/null @@ -1,110 +0,0 @@ -# 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 [Submitting - changes via email][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 -[Working with Gerrit: An example][Gerrit Walkthrough] or -[Basic Gerrit Walkthrough — For GitHub Users][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`