From 30cf83407aec3a63d383cff579e06c83e97d7b5e Mon Sep 17 00:00:00 2001 From: Shikanime Deva Date: Sat, 29 Aug 2026 22:43:29 +0200 Subject: [PATCH] Add in-repo docs for the Devlib project Co-authored-by: Automata Signed-off-by: Shikanime Deva Change-Id: I1819924e285fc7680c2ebfcd0bdbc3166a6a6964 --- docs/Architecture.md | 23 +++++++++++++++++++++++ docs/Development.md | 21 +++++++++++++++++++++ docs/README.md | 18 ++++++++++++++++++ docs/Reference.md | 20 ++++++++++++++++++++ docs/Runbook.md | 26 ++++++++++++++++++++++++++ docs/Troubleshooting.md | 23 +++++++++++++++++++++++ 6 files changed, 131 insertions(+) create mode 100644 docs/Architecture.md create mode 100644 docs/Development.md create mode 100644 docs/README.md create mode 100644 docs/Reference.md create mode 100644 docs/Runbook.md create mode 100644 docs/Troubleshooting.md diff --git a/docs/Architecture.md b/docs/Architecture.md new file mode 100644 index 0000000..0f13563 --- /dev/null +++ b/docs/Architecture.md @@ -0,0 +1,23 @@ + +# Architecture + +`devlib` exposes flake outputs consumed by other repos: + +- `devenvModule` — enables all integrated generators (gitignore, GitHub + workflows, renovate, sops, …). +- `devenvModules.` — composable profiles (`git`, `nix`, `shell`, + `go`, `javascript`, `rust`, `docker`, `elixir`, `ocaml`, …) for a + `devenv.shell`. +- `homeModule` / `homeModules.` — Home Manager modules. +- `flakeModule` — a flake-parts module exposing `treefmt` + `pre-commit` + from a chosen `devenv.shell`. + +Modules live under `modules/` (`devenv/`, `home/`, `flake/`). `devenv/` +splits into `integrations/` (air, buf, ghstack, github, gitignore, license, +renovate, sops), `profiles/` (per-language shells), and `shells/`. +`templates/` holds `default` and `remote` scaffolds (`AGENTS.md`, `flake.nix`). + +## Design intent + +One source of truth for dev-environment hygiene, so every shikanime repo +gets the same git-hooks, formatting, and CI wiring by importing a profile. diff --git a/docs/Development.md b/docs/Development.md new file mode 100644 index 0000000..b80152b --- /dev/null +++ b/docs/Development.md @@ -0,0 +1,21 @@ + +# Development + +## Prerequisites + +- Nix (flakes) and `direnv` — `direnv allow`. + +## Local loop + +```bash +direnv allow +nix flake check # evaluate every module/system +nix fmt # treefmt over Nix/Markdown +``` + +## How to add a module + +1. Add a `.nix` under `modules/devenv/integrations` or `profiles`. +2. Export it from `flake.nix` (e.g. `devenvModules.`). +3. Run `nix flake check`; add a consumer test if it touches outputs. +4. `nix fmt`, then open a PR (stack workflow in `AGENTS.md`). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f165e84 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,18 @@ + +# Devlib — internal docs + +A collection of Nix flake modules that bootstrap a reproducible developer +experience with `devenv`, `git-hooks`, and `treefmt`, plus generator +templates for new repos. + +## Internal ops + +- [Architecture](./Architecture.md) — module set and what each exposes +- [Development](./Development.md) — local check loop +- [Runbook](./Runbook.md) — consume a module, release +- [Troubleshooting](./Troubleshooting.md) — common Nix failures +- [Reference](./Reference.md) — exported modules and profiles + +## User-facing docs + +- [README.md](../README.md) — quick start and module reference diff --git a/docs/Reference.md b/docs/Reference.md new file mode 100644 index 0000000..0ec2411 --- /dev/null +++ b/docs/Reference.md @@ -0,0 +1,20 @@ + +# Reference + +## Exported flake outputs + +- `devenvModule` — all-in-one generator module. +- `devenvModules.` — profiles: `base`, `default`, `git`, `go`, + `javascript`, `nix`, `rust`, `docker`, `elixir`, `ocaml`, `shell`, … +- `homeModule` / `homeModules.` — Home Manager modules. +- `flakeModule` — flake-parts module (treefmt + pre-commit). + +## Integrations + +`air`, `buf`, `ghstack`, `github` (cleanup/commands/integration/javascript/ +nix/release/skaffold/triage), `gitignore`, `license`, `renovate`, `sops`. + +## Templates + +- `templates.default` — `AGENTS.md` + `flake.nix` for a new repo. +- `templates.remote` — remote-scaffold variant. diff --git a/docs/Runbook.md b/docs/Runbook.md new file mode 100644 index 0000000..ee07f28 --- /dev/null +++ b/docs/Runbook.md @@ -0,0 +1,26 @@ + +# Runbook + +## Consume + +Add `devlib` to a flake's inputs (following `README.md`), then import +profiles into a `devenv.shell`: + +```nix +perSystem = _: { + devenv.shells.default.imports = [ + inputs.devlib.devenvModules.git + inputs.devlib.devenvModules.nix + ]; +}; +``` + +## Release + +No published version; consumers pin a git ref. Bump the ref in the +consuming repo when a module changes. + +## Branch protection + +`main` is protected (1 review, linear history, signed commits). Land with +`gh stack merge`. Test modules with `nix flake check` before submitting. diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md new file mode 100644 index 0000000..2fd5901 --- /dev/null +++ b/docs/Troubleshooting.md @@ -0,0 +1,23 @@ + +# Troubleshooting + +## `nix flake check` fails on a new system + +Modules are evaluated per-system. A profile that assumes a tool absent on +some platform breaks `check`. Guard with `lib.optionalAttrs` / `mkIf`. + +## treefmt reformats unexpectedly + +`nix fmt` formats Markdown/Nix/YAML repo-wide. If CI reports drift, run +`nix fmt` locally and commit; never widen the formatter config to hide it. + +## Wrong profile applied + +Profiles are composed by import list, not auto-detected. A missing +`devenvModules.` means that language's tooling is absent — add it to +the shell imports. + +## Consumer flake broke after bump + +Devlib keeps backward compatibility with consumer flakes. If a bump breaks +yours, pin the last-known-good ref and file an issue.