Fix stale Getting Started docs (non-existent staging environment and mismatched layout) #80

Closed
opened 2026-11-15 13:51:14 +00:00 by martin · 0 comments
Owner

Context

Follow-up discovered while preparing #76 (repository transfer to Personal/cluster).

README.md "Getting Started" documents a workflow that does not match the repository:

  • Every example uses a staging environment (just build staging, just bootstrap staging, just switch staging, manifests/staging/, apps-staging). Only dev, infra, and prod exist in flake.nix.
  • The bootstrap recipe does exist (nix run .#nixidy -- bootstrap .#{{ env }} | kubectl apply -f -), but the README does not say it is a one-time action per environment nor what it creates.
  • The repository-structure diagram shows manifests/{env}/apps/, while the generated directories are manifests/{env}/apps-{env}/.
  • The README does not mention the existing just diff {env} recipe or that just switch runs git add ..

Goal

Make the contributor onboarding instructions match the real bootstrap path, just recipes, and generated directory layout, so a new contributor can reproduce the setup without guessing.

Acceptance criteria

  • staging examples in README.md are replaced with dev (or another existing environment).
  • bootstrap is documented as a one-time per-environment step, including what it applies and the resulting Application names (apps-{dev,infra,prod}).
  • Directory names in the repository-structure section match generated output (apps-{env}, argocd, per-app directories).
  • Every documented command is verified to exist in justfile (just --list output matches the docs), and just diff {env} is mentioned for reviewing generated manifests.
  • No generated YAML or encrypted SOPS files are hand-edited.

Related: #76

## Context Follow-up discovered while preparing #76 (repository transfer to `Personal/cluster`). `README.md` "Getting Started" documents a workflow that does not match the repository: - Every example uses a `staging` environment (`just build staging`, `just bootstrap staging`, `just switch staging`, `manifests/staging/`, `apps-staging`). Only `dev`, `infra`, and `prod` exist in `flake.nix`. - The `bootstrap` recipe does exist (`nix run .#nixidy -- bootstrap .#{{ env }} | kubectl apply -f -`), but the README does not say it is a one-time action per environment nor what it creates. - The repository-structure diagram shows `manifests/{env}/apps/`, while the generated directories are `manifests/{env}/apps-{env}/`. - The README does not mention the existing `just diff {env}` recipe or that `just switch` runs `git add .`. ## Goal Make the contributor onboarding instructions match the real bootstrap path, `just` recipes, and generated directory layout, so a new contributor can reproduce the setup without guessing. ## Acceptance criteria - [ ] `staging` examples in `README.md` are replaced with `dev` (or another existing environment). - [ ] `bootstrap` is documented as a one-time per-environment step, including what it applies and the resulting `Application` names (`apps-{dev,infra,prod}`). - [ ] Directory names in the repository-structure section match generated output (`apps-{env}`, `argocd`, per-app directories). - [ ] Every documented command is verified to exist in `justfile` (`just --list` output matches the docs), and `just diff {env}` is mentioned for reviewing generated manifests. - [ ] No generated YAML or encrypted SOPS files are hand-edited. Related: #76
martin changed title from Fix stale Getting Started docs (non-existent just bootstrap recipe and staging environment) to Fix stale Getting Started docs (non-existent staging environment and mismatched layout) 2026-11-15 13:51:57 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/cluster#80
No description provided.