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)
|
||||
* [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)
|
||||
|
|
|
|||
|
|
@ -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