mirror of
https://github.com/smg1024/nix-darwin.git
synced 2026-05-22 20:32:59 +09:00
90 lines
4 KiB
Markdown
90 lines
4 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
This repository is a declarative macOS setup built with Nix flakes, `flake-parts`,
|
|
and a dendritic aspect layout.
|
|
|
|
- `flake.nix` and `flake.lock`: flake entrypoint and pinned inputs.
|
|
- `modules/flake/`: flake assembly, repo options, shared context modules, and
|
|
`darwinConfigurations` generation.
|
|
- `modules/aspects/`: public aspect entry modules auto-discovered with
|
|
`import-tree`. Each aspect may expose `flake.modules.darwin.<feature>` and/or
|
|
`repo.homeModules.<feature>`.
|
|
- `modules/aspects/_*/`: private implementation trees intentionally excluded
|
|
from `import-tree`. Import these manually from the owning aspect to keep each
|
|
feature plug-and-play and in control of its own composition surface.
|
|
- `hosts/`: auto-discovered host declarations that register
|
|
`repo.hosts.<hostname>.system` and a flat `features` list.
|
|
- `secrets/` and `.sops.yaml`: encrypted SOPS files and path rules.
|
|
- `Justfile`: day-to-day contributor commands.
|
|
|
|
Prefer adding a new focused aspect in `modules/aspects/` and keeping host files
|
|
thin. Put reusable internals under a sibling `_/` tree and wire them in
|
|
explicitly from the public aspect entry module.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
Use `just` as the primary interface:
|
|
|
|
- `just darwin <hostname>`: build and switch to the current host (ex: `fenrir`).
|
|
- `just darwin-debug <hostname>`: same as above with verbose trace output.
|
|
- `just fmt .`: format Nix files from the repository root via `nix fmt`
|
|
(Alejandra).
|
|
- `just up`: update all flake inputs.
|
|
- `just upp <input>`: update one input (example: `just upp nixpkgs`).
|
|
- `just history`, `just clean`, `just gc`: inspect and prune Nix
|
|
generations/store.
|
|
|
|
For validation without switching, run:
|
|
`nix build .#darwinConfigurations.fenrir.system --extra-experimental-features 'nix-command flakes'`.
|
|
|
|
For dependency-graph validation without realizing a full build, run:
|
|
`nix build .#darwinConfigurations.fenrir.system --dry-run --extra-experimental-features 'nix-command flakes'`.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
- Use 2-space indentation in `.nix` files and keep attribute sets readable.
|
|
- Run `just fmt .` before committing; formatter is defined in `flake.nix`
|
|
(`alejandra`).
|
|
- Name aspect and helper files in lowercase kebab-case.
|
|
- Keep public aspect filenames aligned with the feature names referenced from
|
|
`repo.hosts.<hostname>.features`.
|
|
- Keep host files declarative and small: they should select features, not carry
|
|
large implementation blocks.
|
|
- Use `imports` inside private `_*/` trees to compose internals, but expose the
|
|
aspect itself through one public entry module in `modules/aspects/`.
|
|
|
|
## Testing Guidelines
|
|
|
|
There is no dedicated unit-test suite in this repo. Treat evaluation/build as
|
|
the test gate:
|
|
|
|
- Run `just fmt .`.
|
|
- Run `nix build .#darwinConfigurations.fenrir.system`.
|
|
- Use `nix build .#darwinConfigurations.fenrir.system --dry-run` for a quick
|
|
validation pass when you only need evaluation and dependency resolution.
|
|
- Use `just darwin-debug <hostname>` when diagnosing evaluation/runtime issues.
|
|
|
|
Document manual verification for user-facing changes (shell, terminal, window
|
|
manager, app defaults, Homebrew behavior).
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
Commit history follows Conventional Commit style: `feat:`, `fix:`, `refactor:`,
|
|
`style:`.
|
|
|
|
- Keep subject lines imperative and concise.
|
|
- Scope each commit to one logical change.
|
|
- In PRs, include: summary, affected modules/paths, command output used for
|
|
validation, and any relevant screenshots for UI changes (for example
|
|
WezTerm/AeroSpace behavior).
|
|
|
|
## Security & Configuration Tips
|
|
|
|
- Never commit plaintext secrets.
|
|
- Store secrets only in `secrets/*.yaml` and manage keys/rules in `.sops.yaml`.
|
|
- `.sops.yaml` currently matches `secrets/.*\.yaml$`; keep new secret files
|
|
within that pattern or update the rule before committing.
|
|
- If adding new secret-backed modules, continue reading from encrypted files via
|
|
the `secrets` aspect rather than hardcoding credentials into aspect modules.
|