docs: Update README for the repository itself r/1669

Adds a lot more information about what is actually going on here, as
well as links to relevant things such as our Monorepo document.

I'm aware that I didn't make all `//...` links clickable, but I
realised at some point that it might be easier to just update cheddar
to support highlighting those natively :-)

Change-Id: Icbb212a6c07a5cf38ab8e65d83a64bec783eb8d0
Reviewed-on: https://cl.tvl.fyi/c/depot/+/1768
Tested-by: BuildkiteCI
Reviewed-by: isomer <isomer@tvl.fyi>
Reviewed-by: kanepyork <rikingcoding@gmail.com>

1 files changed, 74 insertions, 45 deletions

diff --git a/README.md b/README.md
index b5ff0ae166..b3b4da0425 100644
--- a/README.md
+++ b/README.md
@@ -1,80 +1,109 @@
 depot
 =====
 
-[![builds.sr.ht status](https://builds.sr.ht/~tazjin/depot/master.svg)](https://builds.sr.ht/~tazjin/depot/master?)
+[![Build status](https://badge.buildkite.com/016bff4b8ae2704a3bbbb0a250784e6692007c582983b6dea7.svg?branch=canon)](https://buildkite.com/tvl/depot)
 
 This repository is the [monorepo][] for the community around [tazjin's virus
 lounge][tvl], containing our personal tools and infrastructure. Everything in
 here is built using [Nix][].
 
+A large portion of the software here is very self-referential, meaning that it
+exists to sustain the operation of the repository. This is the case because we
+partially see this as [an experiment][] in tooling for monorepos.
+
 If you've ended up here and have no idea who I am, feel free to follow me [on
 Twitter][].
 
 # Highlights
 
-## Tools
-
-* `tools/emacs` contains my personal Emacs configuration (packages & config)
-* `fun/aoc2019` contains solutions for a handful of Advent of Code 2019
-  challenges, before I ran out of interest
-* `tools/blog_cli` contains my tool for writing new blog posts and storing them
-  in the DNS zone
-* `tools/cheddar` contains a source code and Markdown rendering tool
-  that is integrated with my cgit instance to render files in various
-  views
-* `ops/kontemplate` contains my Kubernetes resource templating tool (with which
-  the services in this repository are deployed!)
-* `ops/besadii` contains a tool that runs as the git
-  `post-receive`-hook on my git server to trigger builds on sourcehut.
-* `third_party/nix` contains my fork of the Nix package manager
+## Services
+
+* Source code is available primarily through Sourcegraph on
+  [cs.tvl.fyi](https://cs.tvl.fyi), where it is searchable and even semantically
+  indexed. A lower-tech view of the repository is also available via cgit on
+  [code.tvl.fyi](https://code.tvl.fyi).
+
+  The repository can be cloned using `git` from `https://cl.tvl.fyi/depot`.
+
+* All code in the depot, with the exception of code that is checked in to
+  individual `//users` folders, needs to be reviewed. We use Gerrit on
+  [cl.tvl.fyi](https://cl.tvl.fyi) for this.
+
+* Issues are tracked via our own issue tracker on
+  [b.tvl.fyi](https://b.tvl.fyi). Its source code lives at
+  [`//web/panettone/`][panettone].
+
+* Smaller todo-list entries which do not warrant a separate issue are listed at
+  [todo.tvl.fyi](https://todo.tvl.fyi).
+
+* We use Buildkite for CI. Recent builds are listed on
+  [tvl.fyi/builds](https://tvl.fyi/builds) and pipelines are configured
+  dynamically via
+  [`//ops/pipelines`](https://cs.tvl.fyi/depot/-/tree/ops/pipelines).
+
+All services that we host are deployed on NixOS machines that we manage. Their
+configuration is tracked in `//ops/nixos`.
+
+## Nix
+
+* `//third_party/nix` contains Tvix, [our fork][tvix] of the Nix package manager
+* [`//nix/readTree`](https://cs.tvl.fyi/depot/-/blob/nix/readTree/README.md)
+  contains the Nix code which automatically registers projects in our Nix
+  attribute hierarchy based on their in-tree location
+* `//nix/yants` contains **Y**et **A**nother **N**ix **T**ype **S**ystem, which
+  we use for a variety of things throughout the repository
+* `//nix/buildGo` implements a Nix library that can build Go software in the
+  style of Bazel's `rules_go`. Go programs in this repository are built using
+  this library.
+* `//nix/buildLisp` implements a Nix library that can build Common Lisp
+  software. Currently only SBCL is supported. Lisp programs in this repository
+  are built using this library.
+
+We have a variety of other tools and libraries in the `//nix` folder which may
+be of interest.
 
 ## Packages / Libraries
 
-* `nix/buildGo` implements a Nix library that can build Go software in the style
-  of Bazel's `rules_go`. Go programs in this repository are built using this
-  library.
-* `nix/buildLisp` implements a Nix library that can build Common Lisp
-  software. Currently only SBCL is supported. Lisp programs in this
-  repository are built using this library.
-* `tools/emacs-pkgs` contains various Emacs libraries that my Emacs setup uses,
-  for example:
+* `//net/alcoholic_jwt` contains an easy-to-use JWT-validation library for Rust
+* `//net/crimp` contains a high-level HTTP client using cURL for Rust
+* `//tools/emacs-pkgs` contains various useful Emacs libraries, for example:
   * `dottime.el` provides [dottime][] in the Emacs modeline
   * `nix-util.el` provides editing utilities for Nix files
   * `term-switcher.el` is an ivy-function for switching between vterm buffers
-* `net/alcoholic_jwt` contains an easy-to-use JWT-validation library for Rust
-* `net/crimp` contains a high-level HTTP client using cURL for Rust
+  * `tvl.el` provides helper functions for interacting with the TVL monorepo
+* `//lisp/klatre` provides a grab-bag utility library for Common Lisp
 
-## Services
+## User packages
 
-Services in this repository are deployed on a Google Kubernetes Engine cluster
-using [Nixery][].
+Contributors to the repository have user directories under
+[`//users`](https://cs.tvl.fyi/depot@canon/-/tree/users), which can be used for
+personal or experimental code that does not require review.
 
-* `web/blog` and `web/homepage` contain my blog and website setup
-  (serving at [tazj.in][])
-* `web/cgit-taz` contains a slightly patched version of `cgit` that serves my
-  git web interface at [git.tazj.in][]
-* `ops/journaldriver` contains a small Rust daemon that can forward logs from
-  journald to Stackdriver Logging
+Some examples:
 
-## Miscellaneous
+* `//users/tazjin/homepage` && `//users/tazjin/blog`: A Nix-based static site
+  generator which generates the web page and Atom feed for
+  [tazj.in](https://tazj.in)
+* `//users/tazjin/finito`: A persistent finite-state machine library for Rust.
+* `//users/glittershark/xanthous`: A (WIP) TUI RPG, written in Haskell.
+* `//users/tazjin/emacs`: tazjin's Emacs & EXWM configuration
 
-Presentations I've given in the past are in the `presentations` folder, these
-cover a variety of topics and some of them have links to recordings.
+# Licensing
 
-There's a few fun things in the `fun/` folder, often with context given in the
-README. Check out my [list of the best tools][best-tools] for example.
+Unless otherwise stated in a subdirectory, all code is licensed under the MIT
+license. See [LICENSE](./LICENSE) for details.
 
 # Contributing
 
 If you'd like to contribute to any of the tools in here, please check out the
-[contribution guidelines](./docs/CONTRIBUTING.md).
+[contribution guidelines](./docs/CONTRIBUTING.md) and our [code of
+conduct](./docs/CODE_OF_CONDUCT.md).
 
 [monorepo]: https://en.wikipedia.org/wiki/Monorepo
 [tvl]: https://tvl.fyi
 [Nix]: https://nixos.org/nix
+[an experiment]: https://tvl.fyi/monorepo-doc
 [on Twitter]: https://twitter.com/tazjin
-[Nixery]: https://github.com/google/nixery
-[tazj.in]: https://tazj.in
-[git.tazj.in]: https://git.tazj.in
-[best-tools]: /about/fun/best-tools/README.md
+[panettone]: https://cs.tvl.fyi/depot@canon/-/tree/web/panettone
+[tvix]: https://cs.tvl.fyi/depot/-/blob/third_party/nix/README.md
 [dottime]: https://dotti.me