From f7687b1ea757c75e1eba8e0b2e25feea12719bc0 Mon Sep 17 00:00:00 2001 From: Vincent Ambo Date: Mon, 17 Aug 2020 20:02:19 +0100 Subject: docs: Update README for the repository itself 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 Reviewed-by: kanepyork --- README.md | 119 ++++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 74 insertions(+), 45 deletions(-) (limited to 'README.md') 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 -- cgit 1.4.1