Emma ThorpeandClaude Opus 4.8
33278d9ed2
Document the formatting and lint gates (treefmt/nixfmt/shfmt/prettier, deadnix, statix, pre-commit) and how to run them, so changes -- docs included -- are formatted before commit. Notes the CI detect step that skips heavy checks on docs-only PRs, which can report a false green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
64 lines
3.1 KiB
Markdown
64 lines
3.1 KiB
Markdown
# Working on this flake
|
|
|
|
Project notes for changes to this repository. Persona and memory rules live in
|
|
the user-global config; this file is about the flake's checks and conventions.
|
|
|
|
## Before you commit: run the formatter
|
|
|
|
Formatting and linting are driven by the flake. CI (`.gitea/workflows/ci.yaml`)
|
|
runs `nix flake check`, which fails the build if any file is unformatted or trips
|
|
a lint. From the repo root:
|
|
|
|
- `nix fmt` — format the whole tree (writes changes).
|
|
- `nix flake check` — run every check read-only (what CI runs).
|
|
- `nix develop` — dev shell; its `shellHook` installs the git pre-commit hooks so
|
|
the same gates run on `git commit`.
|
|
|
|
Never commit with `--no-verify`. A bypassed commit ships unformatted content and
|
|
turns CI red on the next push to `main` (see "Docs are checked too").
|
|
|
|
## What gets checked
|
|
|
|
Defined in `flake.nix` (the `treefmt`, `pre-commit`, and `checks` blocks) and
|
|
`statix.toml`:
|
|
|
|
| Check | Tool | Covers |
|
|
| ------------ | --------------------------------- | ------------------------------------------------------- |
|
|
| `formatting` | treefmt → `nixfmt` | all `*.nix` |
|
|
| `formatting` | treefmt → `shfmt` | shell scripts |
|
|
| `formatting` | treefmt → `prettier` | **Markdown, YAML, JSON** (incl. `README.md`, this file) |
|
|
| `deadnix` | deadnix | dead Nix bindings (`--no-lambda-pattern-names`) |
|
|
| `statix` | statix | Nix antipatterns (config in `statix.toml`) |
|
|
| pre-commit | nixfmt-rfc-style, deadnix, statix | the same gates, run on commit |
|
|
|
|
Excluded from formatting: `*/hardware-configuration.nix` (generated by
|
|
`nixos-generate-config`) and `flake.lock`. Editor defaults (indent, EOL, final
|
|
newline) are in `.editorconfig`; note Markdown keeps trailing whitespace, which
|
|
encodes hard line breaks.
|
|
|
|
## Docs are checked too — the common trap
|
|
|
|
prettier formats `*.md`, so **documentation edits must be run through `nix fmt`**
|
|
exactly like code. prettier re-aligns Markdown tables in particular; hand-editing
|
|
a table almost always leaves it non-conformant and fails the `formatting` check.
|
|
|
|
Beware a false green: the CI `detect` step skips the heavy checks on a pull
|
|
request that touches **no** `.nix`, `flake.lock`, or the workflow file — so a
|
|
docs-only PR reports success without ever running prettier. The failure then
|
|
surfaces on the push-to-`main` run (which always runs the full check) or on the
|
|
next unrelated PR that does touch Nix. Run `nix flake check` locally before
|
|
merging a docs change, regardless of what the PR check shows.
|
|
|
|
## Host evaluation
|
|
|
|
CI also evaluates every `nixosConfigurations` / `darwinConfigurations` host's
|
|
toplevel (eval only, no build) on an x86_64 runner, so eval errors fail cheaply.
|
|
Reproduce locally:
|
|
|
|
```sh
|
|
nix eval --raw ".#nixosConfigurations.<host>.config.system.build.toplevel.drvPath"
|
|
```
|
|
|
|
Host lists are discovered from the flake, so adding or removing a host needs no
|
|
change to the workflow.
|