docs(snix): drop contributing/*.md
This has already been migrated to //web. Change-Id: I09f4b405795d94f3c2d6542610d6e38c53b13531 Reviewed-on: https://cl.snix.dev/c/snix/+/30268 Tested-by: besadii Autosubmit: Florian Klink <flokli@flokli.de> Reviewed-by: Ryan Lahfa <masterancpp@gmail.com>
This commit is contained in:
Florian Klink
clbot
parent
b054d6d90f
commit
8e71882141
4 changed files with 0 additions and 224 deletions
|
|
@ -4,11 +4,6 @@
|
||||||
* [Introduction](./introduction.md)
|
* [Introduction](./introduction.md)
|
||||||
* [Getting Started](./getting-started.md)
|
* [Getting Started](./getting-started.md)
|
||||||
|
|
||||||
# Contributing
|
|
||||||
* [Gerrit](./contributing/gerrit.md)
|
|
||||||
* [Email](./contributing/email.md)
|
|
||||||
* [Code & Commits](./contributing/code-&-commits.md)
|
|
||||||
|
|
||||||
# Tvix
|
# Tvix
|
||||||
- [Architecture & data flow](./architecture.md)
|
- [Architecture & data flow](./architecture.md)
|
||||||
- [TODOs](./TODO.md)
|
- [TODOs](./TODO.md)
|
||||||
|
|
|
||||||
|
|
@ -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
|
|
||||||
|
|
@ -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/
|
|
||||||
|
|
@ -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 [<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`
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue