Application and Service Review Checklist

Use this reference during design and again during final review.

Ownership and fragment matrix

Concern	Owner	Typical fragment
User-facing GUI, CLI, editor, or compositor	`modules/applications/<name>/`	`home*.nix`, `nixos.nix`, or `darwin.nix`
User-scoped package and program settings	Application unit	`home.nix` or `home/<class>.nix`
macOS Homebrew package or cask	Owning application or service	`darwin.nix`
Daemon or long-running service	`modules/services/<name>/`	`nixos.nix` or `darwin.nix`
Firewall, group, permission, or service account	Owning service	`nixos.nix` or `darwin.nix`
Upstream module defining options	Owning unit metadata	`meta.nix` under `imports.<class>`
Technical prerequisite unit	Owning unit metadata	Fully qualified `meta.includes`
A set of independent tools chosen for one purpose	Narrowest coherent profile	Profile `meta.includes`
Machine fact such as UUID, monitor ID, or static address	`hosts/<name>/`	Normal host module
Missing or replaced package	`overlays/` only after proving need	Overlay definition

Use home/common.nix when Home Manager configuration is truly shared between NixOS and Darwin. Use home/nixos.nix or home/darwin.nix for class-specific Home Manager behavior. Root common.nix is system-side and never Home Manager. Do not create an unused counterpart for symmetry.

Dependency review

For every edge from unit A to unit B, answer these questions:

Does A fail to work without B? If yes, put the fully qualified ID of B in A's meta.includes.
Are A and B merely useful together for a particular workflow? If yes, let a profile include both.
Does the dependency exist only on one host? Keep the machine fact in the host, but keep reusable behavior in its unit or profile.
Is a new specialArgs, _module.args, Registry field, or direct my.*.enable assignment being proposed? Reject it unless the repository's normal module and meta.includes mechanisms provably cannot model the requirement.
Would adding the dependency make the depended-on application select a compositor, desktop, personal workload, or unrelated tool? Reverse or remove the edge; application metadata contains technical requirements, not taste.

Accept no circular dependency, shortened unit ID, duplicate include, stale unit ID, or ordering-dependent override.

Minimality and code-quality review

Reject any of these patterns:

Empty or placeholder reserved fragments.
Hand-written enable options or guards already generated by the Registry.
Top-level imports, options, or config in a configuration fragment.
External module imports hidden in a guarded configuration fragment.
Helper files assumed to be auto-imported.
A helper abstraction used once without reducing meaningful complexity.
Configuration duplicated across fragments when a shared fragment can express it cleanly.
Direct host application or unit selection where a profile expresses the concern.
A new flake input or overlay when the locked package set already provides the package and required module.
Global argument injection for a value owned by one unit.
lib.mkForce used to win an ordering fight instead of resolving ownership.
Secret material, generated state, machine IDs, or mutable user preferences committed as reusable configuration.
Comments that repeat the code, compatibility aliases, dead options, or opportunistic unrelated cleanup.

Prefer standard upstream module options over hand-written service definitions. Prefer existing repository arguments and helpers over new plumbing. Preserve user-owned mutable state unless the requested policy explicitly owns it.

Validation matrix

Run checks from the repository root and keep the exact results for the handoff. Do not switch or activate a live system merely to validate a change.

Always

Format task-owned files. If the worktree contains unrelated user changes, pass only task-owned paths to the configured formatter when supported.
Run git diff --check.
Review git status --short, git diff --stat, and the complete git diff.
Run nix flake check.
Run pre-commit run --all-files.

NixOS or Home Manager on NixOS

Evaluate each affected host's system toplevel derivation.
Build at least one affected NixOS configuration with --no-link when the current system supports it.
Inspect the resulting option that proves selection: for example environment.systemPackages, the user's home.packages, systemd.services, users.users.<name>.extraGroups, or the upstream programs/services option.

Typical build shape:

nix build .#nixosConfigurations.<host>.config.system.build.toplevel --no-link

nix-darwin or Home Manager on Darwin

Evaluate every affected Darwin host even when running on Linux.
Inspect homebrew.casks or homebrew.brews for Homebrew-backed additions.
Evaluate the relevant Home Manager program or package option.
Build a Darwin configuration only on a compatible Darwin builder; otherwise report that build as an explicit runtime-validation gap.

Typical evaluation shapes:

nix eval --raw .#darwinConfigurations.<host>.system.drvPath
nix eval --json .#darwinConfigurations.<host>.config.homebrew.casks

Confirm the exact output attribute against the current flake before using a command; do not paste these shapes blindly.

Profiles and cross-platform changes

Determine transitive selection through meta.includes, not only direct mentions.
Evaluate every real host selecting the changed profile.
Evaluate both host classes for a cross-platform profile, even if only one current fragment changed.
Re-read modules/profiles/README.md and hosts/default.nix for stale meaning, compatibility, or role statements.
If no real host selects the new unit, construct a non-persistent evaluation that enables it or explain why the unit is intentionally dormant. Do not add a fake host or permanent direct selection as a test harness.

Runtime-dependent behavior

Evaluation and builds cannot prove GUI appearance, credentials, network access, hardware behavior, or successful daemon interaction. State the precise manual post-activation check needed for those behaviors. Never describe evaluation as a runtime test.

7.0 KiB Raw Blame History