docs(nix): apply writing conventions

This commit is contained in:
2026-08-28 09:52:05 -04:00
parent 8cc171974a
commit f3494be6cc

View File

@@ -1,7 +1,7 @@
# Nix Conventions
This document records local Nix style and design conventions.
Prefer these conventions when changing this flake.
Use these conventions when changing this flake.
## Names
@@ -33,10 +33,10 @@ Use:
### Use closed interfaces for helper imports
Use exact function argument patterns when an imported helper file has a closed interface.
A helper file has a closed interface when the importer owns the argument set.
The imported file must name each accepted attribute.
This rejects stale or accidental extra attributes.
Use exact function argument patterns for helper imports with closed interfaces.
A helper import has a closed interface when the caller owns the argument set.
The imported file names each accepted attribute.
It rejects stale or accidental extra attributes.
Avoid:
@@ -82,7 +82,7 @@ import ./flake {
### Keep NixOS module interfaces open
NixOS modules must accept extra arguments because the module system owns their argument shape.
NixOS modules accept extra arguments because the module system owns their argument shape.
Name the arguments the module uses.
Keep `...` so the module accepts standard module arguments and special arguments.
@@ -111,7 +111,7 @@ Use:
### Use `@` for forwarding wrappers
Use `@` when a wrapper must pass the complete argument set to another module function.
Use `@` when a wrapper passes the complete argument set to another module function.
Name the arguments the wrapper uses before `...`.
Forward the bound argument set unchanged.
@@ -134,7 +134,7 @@ dotfiles.guest { name = "sample"; } args
### Use `let` for important intermediate values
Use a `let` binding when it names an important intermediate value.
Use a `let` binding when it avoids repeating a complex expression.
Use a `let` binding when it avoids repeated complex expressions.
Do not use a `let` binding only to shorten a standard library call.
Avoid:
@@ -156,7 +156,7 @@ lib.mapAttrs f attrs
### Qualify standard library calls in flake assembly
Prefer qualified standard library calls inside flake assembly code.
Use qualified standard library calls inside flake assembly code.
Use `lib.mapAttrs` instead of inheriting `mapAttrs` from `lib`.
This keeps the source of helper functions visible.
@@ -181,9 +181,9 @@ lib.mapAttrs f attrs
Keep flake assembly code under `flake/`.
Keep `flake.nix` focused on inputs and public outputs.
A public output is any attribute returned by the flake `outputs` function.
Another flake can reference a public output through `inputs.<name>.<output>`.
Tools such as `nix flake show` also display public outputs.
The `outputs` function returns each public output as an attribute.
An external flake reads public outputs through `inputs.<name>.<output>`.
`nix flake show` also displays public outputs.
Avoid: