diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md deleted file mode 100644 index 0e46bbedb..000000000 --- a/docs/CODE_OF_CONDUCT.md +++ /dev/null @@ -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. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md deleted file mode 100644 index 30863b11b..000000000 --- a/docs/CONTRIBUTING.md +++ /dev/null @@ -1,59 +0,0 @@ -Contribution Guidelines -======================= - - -**Table of Contents** - -- [Contribution Guidelines](#contribution-guidelines) - - [Before making a change](#before-making-a-change) - - [Builds \& tests](#builds--tests) - - [Submitting changes](#submitting-changes) - - - -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 diff --git a/docs/REVIEWS.md b/docs/REVIEWS.md deleted file mode 100644 index 2bea3173a..000000000 --- a/docs/REVIEWS.md +++ /dev/null @@ -1,210 +0,0 @@ -TVL Code Reviews -================ - - -**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) - - - - -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/` 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 diff --git a/docs/designs/SPARSE_CHECKOUTS.md b/docs/designs/SPARSE_CHECKOUTS.md deleted file mode 100644 index beb18c151..000000000 --- a/docs/designs/SPARSE_CHECKOUTS.md +++ /dev/null @@ -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 diff --git a/docs/history.md b/docs/history.md deleted file mode 100644 index c30b7236d..000000000 --- a/docs/history.md +++ /dev/null @@ -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. - - diff --git a/docs/importing-projects.md b/docs/importing-projects.md deleted file mode 100644 index c68c8b190..000000000 --- a/docs/importing-projects.md +++ /dev/null @@ -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).