maurice/snix
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: drop docs/ directory

Browse source 
This doesn't document any of Snix, but is a leftover from the TVL.

It probably should have been deleted as part of
df4500ea2b.

Change-Id: I1be5a743b66d786a1b6861d2f0d9e325b7be5f7c
Reviewed-on: https://cl.snix.dev/c/snix/+/30298
Tested-by: besadii
Autosubmit: Florian Klink <flokli@flokli.de>
Reviewed-by: Ilan Joselevich <personal@ilanjoselevich.com>
This commit is contained in:
Florian Klink 2025-04-04 16:10:56 +01:00 • committed by clbot
parent 06ffeec464
commit cfa186c6a8
6 changed files with 0 additions and 450 deletions
Download patch file Download diff file Expand all files Collapse all files

29
docs/CODE_OF_CONDUCT.md
View file

@ -1,29 +0,0 @@
A SERMON ON ETHICS AND LOVE
===========================
One day Mal-2 asked the messenger spirit Saint Gulik to approach the
Goddess and request Her presence for some desperate advice. Shortly
afterwards the radio came on by itself, and an ethereal female Voice
said **YES?**
"O! Eris! Blessed Mother of Man! Queen of Chaos! Daughter of Discord!
Concubine of Confusion! O! Exquisite Lady, I beseech You to lift a
heavy burden from my heart!"
**WHAT BOTHERS YOU, MAL? YOU DON'T SOUND WELL.**
"I am filled with fear and tormented with terrible visions of pain.
Everywhere people are hurting one another, the planet is rampant with
injustices, whole societies plunder groups of their own people,
mothers imprison sons, children perish while brothers war. O, woe."
**WHAT IS THE MATTER WITH THAT, IF IT IS WHAT YOU WANT TO DO?**
"But nobody Wants it! Everybody hates it."
**OH. WELL, THEN *STOP*.**
At which moment She turned herself into an aspirin commercial and left
The Polyfather stranded alone with his species.
SINISTER DEXTER HAS A BROKEN SPIROMETER.

59
docs/CONTRIBUTING.md
View file

@ -1,59 +0,0 @@
Contribution Guidelines
=======================
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**
- [Contribution Guidelines](#contribution-guidelines)
- [Before making a change](#before-making-a-change)
- [Builds \& tests](#builds--tests)
- [Submitting changes](#submitting-changes)
<!-- markdown-toc end -->
This is a loose set of "guidelines" for contributing to the depot. Please note
that we will not accept any patches that don't follow these guidelines.
Also consider the [code of conduct](./CODE_OF_CONDUCT.md). No really,
you should.
## Before making a change
Before making a change, consider your motivation for making the change.
Documentation updates, bug fixes and the like are *always* welcome.
When adding a feature you should consider whether it is only useful for your
particular use-case or whether it is generally applicable for other users of the
project.
When in doubt - just ask! You can reach out to us via mail at
[depot@tvl.su](mailto:depot@tvl.su) or on IRC.
## Builds & tests
All projects are built using [Nix][] to avoid "build pollution" via the user's
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` from the repository root. `//tools/magrathea`
(which is added to `PATH` automatically if you enable [direnv][])
allows you to do the same via `mg build //tools/foo`
regardless of what your working directory is.
If the project has tests, check that they still work before submitting your
change.
## Submitting changes
The code review & change submission process is described in the [code
review][] documentation.
[magit]: https://magit.vc/
[Nix]: https://nixos.org/nix/
[code review]: ./REVIEWS.md
[Importing projects into depot]: ./importing-projects.md
[direnv]: https://direnv.net

210
docs/REVIEWS.md
View file

@ -1,210 +0,0 @@
TVL Code Reviews
================
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**
- [TVL Code Reviews](#tvl-code-reviews)
- [Registration](#registration)
- [Gerrit setup](#gerrit-setup)
- [Gerrit workflows](#gerrit-workflows)
- [Review process & approvals](#review-process--approvals)
- [Submitting changes via email](#submitting-changes-via-email)
- [Gerrit for GitHub users](#gerrit-for-github-users)
<!-- markdown-toc end -->
This document describes the TVL code review process & tooling. If you are
looking for general contribution guidelines, please look at the [general
contribution guidelines](./CONTRIBUTING.md).
All changes are tracked at [cl.tvl.fyi](https://cl.tvl.fyi) using Gerrit. See
[Registration](#registration) for information on how to register an account.
## Registration
The preferred method of contributions & review is done via Gerrit.
For quick drive-by contributions, TVL’s Gerrit supports single sign-on (SSO)
using a GitHub, StackOverflow or GitLab.com account (or alternatively, you
can [submit changes via email](#submitting-changes-via-email)).
In general, we recommend to create a TVL-specific LDAP account on the Gerrit
instance by following these instructions:
1. Be a member of `#tvl` on [hackint][].
2. Clone the depot locally (via `git clone "https://cl.tvl.fyi/depot"`).
3. Create a user entry in our LDAP server in [ops/users][ops-users].
The entry can be generated using [//web/pwcrypt](https://signup.tvl.fyi/).
4. Create a commit adding yourself (see e.g.
[CL/2671](https://cl.tvl.fyi/c/depot/+/2671))
5. If only using LDAP, submit the patch via email (see
[Submitting changes via email](#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, [tell Gerrit][Gerrit SSH] about your SSH keys.
Then, to make using Gerrit smooth for users, the repository should be cloned and
a commit hook installed as follows:
```
git clone "ssh://$USER@code.tvl.fyi:29418/depot"
curl -Lo depot/.git/hooks/commit-msg https://cl.tvl.fyi/tools/hooks/commit-msg
chmod +x depot/.git/hooks/commit-msg
```
If you have a previous clone of the depot via HTTP you can use `git remote
set-url` to update the origin URL and install the hook in the same way as above.
## Gerrit workflows
The developer workflow on Gerrit is quite different from what GitHub-users are
used 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.
Changes should usually be based on the remote `HEAD` (the `canon` branch).
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.
Sending a change for review is done by pushing to a special target. You can set
this to be the default push target through your git configuration:
```
git config remote.origin.url "ssh://$USER@code.tvl.fyi:29418/depot"
git config remote.origin.push HEAD:refs/for/canon
```
Then, after making your change, push to the default, or to a special target:
```
# Example:
git commit -m 'docs(REVIEWS): Fixed all the errors in the reviews docs'
git push origin
# Uploading a work-in-progress CL:
git push origin HEAD:refs/for/canon%wip
```
TIP: Every individual commit will become a separate change. We do not squash
related commits, but instead submit them one by one. If you need to add a
lot of commits to depot in one go, e.g. for importing a preexisting project,
[you can create a special merge commit][importing-projects]) under some
circumstances.
During your review, the reviewer(s) might ask you to make changes. You can
simply amend your commit(s) and push to the same ref. Gerrit will automatically
update your changes.
Read more about the Gerrit workflow in the [Gerrit walkthrough][].
## Review process & approvals
Each user has the ability to create their own users directory in
`//users/<username>` in which they can submit code without review from other
contributors (they will still need to +2 their own changes, and the initial
check-in of the `OWNERS` file needs to be reviewed).
You can set a directory like this up for yourself by proposing a change similar
to [CL/246](https://cl.tvl.fyi/c/depot/+/246).
For all paths outside of `//users`, code review is required. We have no strict
guidelines about the review process itself, as we're not a megacorp, but we have
formalised checks before submitting:
* At least one person who is [an owner][OWNERS] of the codepath must have given
a +2 review
* The commit message must conform to our [guidelines][]
* No code review comments must be left unresolved
If all these conditions are fulfilled, the **change author submits their change
themselves**.
## Submitting changes via email
Please keep in mind this process is more complicated and requires more work from
both sides:
- Someone needs to relay potential comments from Gerrit to you, you won't get
emails from Gerrit.
- Uploading new revisions needs to be done by the person sending it to Gerrit
on your behalf.
- If you decide to get a Gerrit account later on, existing CLs need to be
abandoned and recreated (as CLs can't change Owner).
This causes earlier reviews to be more disconnected, and thus more churn.
We provide local accounts and do SSO with various third-parties, so getting the
account should usually be low-friction.
If you still decide differently, you can submit a patch via email to
`depot@tvl.su` and it will be added to Gerrit by a contributor.
Create an appropriate commit locally and 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.
For more details, refer to the [official git documentation][git-contributing-email].
The email address is a [public inbox][].
## Gerrit for GitHub Users
There is a walkthrough that describes [only the parts that differ
from GitHub][github-diff], although it does not cover [attention
sets][], which are important to understand.
### Attention Sets
The attention set of a CL is somewhat similar to the set of GitHub
users who have unread notifications for a PR. The "your turn" list
on the dashboard is similar to your unread notifications list in
GitHub. These similarities are only rough approximations, however.
Unfortunately the rules for updating attention sets are very
different and complex. If you don't read and understand them, you
may end up leaving comments that nobody ever finds out about. Here
are a few unexpected features:
- Voting on or replying to a CL will remove you from the attention
set. You can also do this by clicking on the gray chevron shape
next to your name.
- If you comment on a merged or abandoned change without marking
your comment "unresolved", *nobody will be notified of your
comment*. If you want to the owner of a merged or abandoned
change to read your comment, you must mark it as "unresolved" or
manually add them to the attention set by hovering your mouse over
their name and clicking "add to attention set"
There are many more [rules][attention-set-rules], which you should
read.
[Gerrit SSH]: https://cl.tvl.fyi/settings/#SSHKeys
[Gerrit walkthrough]: https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough.html
[OWNERS]: https://cl.tvl.fyi/plugins/owners/Documentation/config.md
[guidelines]: ./CONTRIBUTING.md#commit-messages
[ops-users]: ../ops/users/default.nix
[public inbox]: https://inbox.tvl.su/depot/
[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
[git-contributing-email]: https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_project_over_email
[importing-projects]: ./importing-projects.md

43
docs/designs/SPARSE_CHECKOUTS.md
View file

@ -1,43 +0,0 @@
NOTE: This proposal is archived. We run `josh` instead, and long-term
might want to integrate per-target dependency analysis with josh's
workspace functionality.
-------------
Below is a prototype for a script to create Git sparse checkouts of the depot.
The script below works today with relatively recent versions of git.
Open items:
- Read-increment-write the checkout ID from a file in .git.
- `NICE_CHECKOUT_ROOT` should be a git configuration value.
- `tvl-get-depends` will be a script that contacts the build farm and asks for
the closure of a given source directory, using [depot-scan].
```bash
DEPOT_ROOT="${depot.path}"
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
CLIENT_ROOT="$XDG_DATA_HOME/tvlc/clients"
NICE_CHECKOUT_ROOT="$HOME/tvlc"
CHECKOUT_ID=1
CHECKOUT_NAME=myclient # command line variables
assertAbsolutePath "$CLIENT_ROOT"
mkdir "$CLIENT_ROOT"/"$CHECKOUT_ID"
ln -s "$CLIENT_ROOT"/"$CHECKOUT_ID" "$NICE_CHECKOUT_ROOT"/"$CHECKOUT_NAME"
cd "$DEPOT_ROOT"
git worktree add --no-checkout -b "tvlc-$CHECKOUT_ID" "$CLIENT_ROOT/$CHECKOUT_ID/" canon
# BUG: git not creating the /info/ subdir
mkdir "$DEPOT_ROOT"/.git/worktrees/"$CHECKOUT_ID"/info
cd "$CLIENT_ROOT/$CHECKOUT_ID"
git sparse-checkout init --cone
git sparse-checkout set "$TARGET_DIR" nix/readTree overrides
tvl-get-depends "$TARGET_DIR" | xargs git sparse-checkout add
cd "$NICE_CHECKOUT_ROOT"/"$CHECKOUT_NAME"
```
[depot-scan]: ../../users/edef/depot-scan

18
docs/history.md
View file

@ -1,18 +0,0 @@
Historical Notes on depot
=========================
This document collects references to documentation, design documents,
code etc. that are no longer accurate nor used, but are of interest as
historical background for the current state of depot. A comprehensive
overview of the history of depot remains future work.
- [The TVL Monorepo](https://tvl.fyi/monorepo-doc),
original (?) living design document for depot.
- [Sparse Checkouts](designs/SPARCE_CHECKOUTS.md),
a proposal for a tool to create sparse checkouts of depot.
<!--
TODO(sterni): include other Google Docs I have links to?
Questionable whether it is worth it in all cases, as some of them may
have never been shared beyond ##?tvl(-dev)?. Interested in opinions.
-->

91
docs/importing-projects.md
View file

@ -1,91 +0,0 @@
Importing projects into depot
=============================
Before importing an existing `git`-based project into depot, a few questions
need to be answered:
* Is the project licensed under a free software license, or public domain?
* Do you need to import existing history?
* Do you need to export new history with hashes that continue on from the old
history? (e.g. importing an existing repository, and exporting from depot to
the old upstream)
Think about this and then pick an approach below:
## Import with no history (just commit)
Simply copy the files to where you want them to be in depot, and commit. Nothing
else to do!
## Import without continuous history (subtree merge)
This import approach lets you drop an existing project into depot, keep its
existing history, but not retain the ability to continue external history.
This means that if you, for example, import a project from a different git host
using this method, and then continue to commit to it inside of depot, you will
not be able to export a history consistent with your previous hashes using
`josh`.
Commit hashes before the import will exist in depot and be valid.
Still, this approach might be viable if a project "moves into" depot, or has
nothing depending on it externally.
1. Pick a location in depot where you want your project to be (`$loc` from now on).
2. Fetch your project into the same git store as your depot clone (e.g. by
adding it as an upstream and fetching it).
3. Pick the commit you want to merge (`$commit` from now on).
4. Run `git subtree add --prefix=$loc $commit`, which will create the correct
merge commit.
5. Ensure Gerrit [knows about your commit](#preparing-merges-in-gerrit) for the
parent that is being merged.
6. Modify the merge commit's message to start with `subtree($project_name):`.
Gerrit **will not** allow merge commits that do not follow this format.
7. Push your subtree commit for review as normal.
## Import with continuous history
This approach imports the history using `josh`, which means that external
history before/after the import is consistent (you can continue committing in
`depot`, export the history back out, and from an external perspective nothing
changes).
This is what we did with repositories like `nix-1p` and `nixery`.
Note: Inside of depot, the pre-import commit hashes will **not make sense**.
`josh` will rewrite them in such a way that exporting the project will yield the
same hashes, but this rewriting changes the hashes of your commits inside of
depot.
1. Pick a location in depot where you want your project to be (`$loc`).
2. Fetch your project into the same git store as your depot clone (e.g. by
adding it as an upstream and fetching it).
3. Check out the commit you want to merge into depot.
4. Run `josh-filter ":prefix=$loc"`, and take note of the `FILTERED_HEAD` ref
that it produces (`$filtered` from now on).
5. Ensure Gerrit [knows about the filtered commit](#preparing-merges-in-gerrit).
6. Merge the filtered commit into depot using a standard merge, but make sure to
add the `--allow-unrelated-histories` flag. Your commit message **must**
start with `subtree($project_name):`, otherwise Gerrit will not let you push
a merge.
7. Push the merge commit for review as usual.
------------------------------------------------------
## Preparing merges in Gerrit
When pushing a merge to Gerrit, it needs to know about all ancestors of the
merge, otherwise it will try to interpret commits as new CLs and reject them for
not having a change ID (or create a huge number of CLs, if they do have one).
To prevent this, we have a special git ref called `subtree-staging` which you
can push external trees to.
Access to `subtree-staging` has to be granted by a TVL admin, so ping tazjin,
lukegb, flokli, sterni and so on before proceeding.
1. Determine the commit you want to merge (`$commit`).
2. Run `git push -f $commit origin/subtree-staging` (or replace `origin` with
whatever the TVL Gerrit remote is called in your clone).