mirror of
https://github.com/moons-14/dotfiles.git
synced 2026-10-06 08:48:11 +09:00
140 lines
7.0 KiB
Markdown
140 lines
7.0 KiB
Markdown
# 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:
|
|
|
|
1. Does A fail to work without B? If yes, put the fully qualified ID of B in
|
|
A's `meta.includes`.
|
|
2. Are A and B merely useful together for a particular workflow? If yes, let a
|
|
profile include both.
|
|
3. Does the dependency exist only on one host? Keep the machine fact in the
|
|
host, but keep reusable behavior in its unit or profile.
|
|
4. 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.
|
|
5. 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
|
|
|
|
1. Format task-owned files. If the worktree contains unrelated user changes,
|
|
pass only task-owned paths to the configured formatter when supported.
|
|
2. Run `git diff --check`.
|
|
3. Review `git status --short`, `git diff --stat`, and the complete `git diff`.
|
|
4. Run `nix flake check`.
|
|
5. 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|