mirror of
https://github.com/smg1024/nix-darwin.git
synced 2026-05-22 20:32:59 +09:00
69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
This repository is a declarative macOS setup built with Nix flakes.
|
|
|
|
- `flake.nix` and `flake.lock`: entrypoint and pinned inputs.
|
|
- `modules/`: system-level nix-darwin modules (`nix-core.nix`, `system.nix`,
|
|
`apps.nix`, `host-users.nix`).
|
|
- `home/`: Home Manager user configuration, with feature modules such as
|
|
`git.nix`, `zsh.nix`, and `nvf/`.
|
|
- `secrets/`: encrypted SOPS files (for example `secrets/poby.yaml`).
|
|
- `Justfile`: day-to-day contributor commands.
|
|
|
|
Prefer adding new configuration as small focused modules, then importing them
|
|
from `home/default.nix` or `flake.nix`.
|
|
|
|
## 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 all Nix files via `nix fmt` (Alejandra).
|
|
- `just up`: update all flake inputs.
|
|
- `just upp <input>`: update one input (example: `just upp nixpkgs-darwin`).
|
|
- `just history`, `just gc`, `just clean`: inspect and prune Nix
|
|
generations/store.
|
|
|
|
For validation without switching, run:
|
|
`nix build .#darwinConfigurations.fenrir.system --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 module files in lowercase kebab-case (example: `host-users.nix`).
|
|
- Keep modules single-purpose and compose through `imports`.
|
|
|
|
## 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 `just darwin-debug` when diagnosing evaluation/runtime issues.
|
|
|
|
Document manual verification for user-facing changes (shell, terminal, window
|
|
manager, app defaults).
|
|
|
|
## 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`.
|
|
- If adding new secret files, ensure `path_regex` coverage and encrypted content
|
|
before pushing.
|