From 8eaa3a47034ff0cc1ff204ab627984da4f77cb2d Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 9 Aug 2026 06:34:52 +0000 Subject: [PATCH] docs: backfill architecture decision records for earlier decisions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The document-classification ADR introduced in the skip-non-workloads change was numbered 0001, but it is a late, narrow decision. Backfill the higher-level decisions that predate it so the ADR log reflects the real architecture, numbered chronologically. Records six decisions (terse; each dated to when it was actually made and marked recorded-retrospectively): 0001 typed Kubernetes decoding + fixed workload kinds (accepted, under reconsideration — #26) 0002 positional-argument CLI input model, with `-` for stdin 0003 cmd → processor → yamlparser → k8s package layout 0004 golden/approval testing 0005 in-process Run(args, stdin, stdout, stderr) int seam 0006 Conventional Commits + automated releases CONTRIBUTING.md points contributors (human and AI) at docs/adr/ so the decisions are read and kept current. The document-classification ADR is renumbered to 0007 in its own change. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Pc6NAURAqjU4LYJx93tgSC --- CONTRIBUTING.md | 8 ++++++++ docs/adr/0001-typed-kubernetes-decoding.md | 13 +++++++++++++ docs/adr/0002-cli-input-model.md | 11 +++++++++++ docs/adr/0003-package-layout.md | 11 +++++++++++ docs/adr/0004-approval-testing.md | 13 +++++++++++++ docs/adr/0005-run-entry-point-seam.md | 12 ++++++++++++ .../0006-conventional-commits-and-releases.md | 14 ++++++++++++++ docs/adr/README.md | 18 ++++++++++++++++++ 8 files changed, 100 insertions(+) create mode 100644 docs/adr/0001-typed-kubernetes-decoding.md create mode 100644 docs/adr/0002-cli-input-model.md create mode 100644 docs/adr/0003-package-layout.md create mode 100644 docs/adr/0004-approval-testing.md create mode 100644 docs/adr/0005-run-entry-point-seam.md create mode 100644 docs/adr/0006-conventional-commits-and-releases.md create mode 100644 docs/adr/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4151ad8..3cb8ce5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,14 @@ gofmt -l . # should print nothing CI runs `gofmt`, `go vet`, `go mod tidy` verification, and `go test -race`, so run them locally before opening a pull request. +## Architecture decisions + +Design decisions are recorded as ADRs in [`docs/adr/`](docs/adr/). Read them +before changing how `kir` is structured or behaves — they explain why the +current design is the way it is. If a change revisits a decision, update or +supersede the relevant ADR in the same pull request; add a new ADR for a new +decision. This applies to human and AI contributors alike. + ## Commit messages This project uses [Conventional Commits](https://www.conventionalcommits.org). diff --git a/docs/adr/0001-typed-kubernetes-decoding.md b/docs/adr/0001-typed-kubernetes-decoding.md new file mode 100644 index 0000000..3bb16d0 --- /dev/null +++ b/docs/adr/0001-typed-kubernetes-decoding.md @@ -0,0 +1,13 @@ +# 1. Extract images by decoding manifests with the typed Kubernetes scheme + +- Status: accepted — **under reconsideration (#26)** +- Date: 2025-03-13 _(recorded retrospectively 2026-08-08)_ + +Decode each document with the typed client-go scheme and read the PodSpec via a +type switch over a fixed set of workload kinds (`Pod`, `Deployment`, `DaemonSet`, +`ReplicaSet`, `StatefulSet`, `Job`, `CronJob`). Anything else yields no images. + +Precise and dependency-light, but only the hardcoded kinds are understood: +custom resources that embed a PodSpec (Argo Rollouts, Knative, …) are silently +missed. #26 proposes finding the PodSpec structurally instead (Cue in #27–#30) +and #75 catalogs what's missed — hence "under reconsideration". diff --git a/docs/adr/0002-cli-input-model.md b/docs/adr/0002-cli-input-model.md new file mode 100644 index 0000000..0fb0d26 --- /dev/null +++ b/docs/adr/0002-cli-input-model.md @@ -0,0 +1,11 @@ +# 2. Take manifest sources as positional arguments, with `-` for stdin + +- Status: accepted +- Date: 2025-03-13 _(recorded retrospectively 2026-08-08)_ + +Manifest sources are positional arguments — each a file, a directory (expanded), +or a shell glob; a single `-` reads a stream from stdin. No input flags. + +Composes with the shell (`kir manifests/*.yaml`, `kubectl get … -o yaml | kir -`) +and follows the Unix filter convention. `-` is an overloaded sentinel, so +argument resolution (`fileutil`) special-cases it against real paths. diff --git a/docs/adr/0003-package-layout.md b/docs/adr/0003-package-layout.md new file mode 100644 index 0000000..d81d644 --- /dev/null +++ b/docs/adr/0003-package-layout.md @@ -0,0 +1,11 @@ +# 3. Layer the code as cmd → processor → yamlparser → k8s + +- Status: accepted +- Date: 2025-03-17 _(recorded retrospectively 2026-08-08)_ + +One-directional flow `main → cmd → processor → yamlparser → k8s`, with `fileutil` +for argument/glob resolution: `cmd` wires the CLI, `processor` orchestrates per +source, `yamlparser` decodes documents, `k8s` pulls the PodSpec and images. + +Each layer is unit-testable in isolation and new behavior has an obvious home, at +the cost of more packages than a tool this size strictly needs. diff --git a/docs/adr/0004-approval-testing.md b/docs/adr/0004-approval-testing.md new file mode 100644 index 0000000..25d9c0c --- /dev/null +++ b/docs/adr/0004-approval-testing.md @@ -0,0 +1,13 @@ +# 4. Pin behaviour with golden (approval) tests + +- Status: accepted +- Date: 2025-03-18 _(recorded retrospectively 2026-08-08)_ + +Use [`go-approval-tests`](https://github.com/approvals/go-approval-tests): run +real manifests through `kir` and compare output against committed +`*.approved.txt` goldens (replacing an informal `examples/` dir). Later refined +to capture stdout, stderr, and the exit code separately through one seam +(ADR 0005). + +Adding a case is cheap (drop a manifest, approve output) and the goldens double +as documentation; intentional output changes require an explicit approve step. diff --git a/docs/adr/0005-run-entry-point-seam.md b/docs/adr/0005-run-entry-point-seam.md new file mode 100644 index 0000000..36207c0 --- /dev/null +++ b/docs/adr/0005-run-entry-point-seam.md @@ -0,0 +1,12 @@ +# 5. Expose the CLI as an in-process `Run(args, stdin, stdout, stderr) int` + +- Status: accepted +- Date: 2026-08-02 _(recorded retrospectively 2026-08-08)_ + +The whole CLI is one function `Run(args []string, stdin io.Reader, stdout, stderr +io.Writer) int` — no `os.Exit`, no global streams. `main.go` only wires the real +`os` values and calls `os.Exit(Run(...))`; golden tests (ADR 0004) call `Run` and +capture the (stdout, stderr, exit code) triple. + +The full CLI contract is exercised in-process; every path threads the four +parameters instead of reaching for globals. diff --git a/docs/adr/0006-conventional-commits-and-releases.md b/docs/adr/0006-conventional-commits-and-releases.md new file mode 100644 index 0000000..aad2b3f --- /dev/null +++ b/docs/adr/0006-conventional-commits-and-releases.md @@ -0,0 +1,14 @@ +# 6. Automate releases from Conventional Commits + +- Status: accepted +- Date: 2026-08-06 _(recorded retrospectively 2026-08-08)_ + +Commit messages and PR titles follow +[Conventional Commits](https://www.conventionalcommits.org/). release-please +derives the version and `CHANGELOG.md` from commit types on `master`; GoReleaser +builds and publishes artifacts. `fix:`/`perf:` → patch, `feat:` → minor, +`feat!:`/`BREAKING CHANGE:` → major; `ci|build|docs|refactor|test|chore` → none. +Renovate emits `fix(deps):`/`ci(deps):`. + +No manual release steps, but a mistyped type mis-classifies a release, and +squash-merges make the PR title load-bearing. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..a3b2dd3 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,18 @@ +# Architecture Decision Records + +Short records of the significant architectural decisions in `kir`, in the order +they were made. See Michael Nygard's +[Documenting architecture decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) +for the format. + +ADRs 0001–0006 were recorded retrospectively (on 2026-08-08); each carries the +date the decision was actually made. + +| ADR | Decision | Date | +| --- | --- | --- | +| [0001](0001-typed-kubernetes-decoding.md) | Extract images by decoding manifests with the typed Kubernetes scheme (under reconsideration — #26) | 2025-03-13 | +| [0002](0002-cli-input-model.md) | Take manifest sources as positional arguments, with `-` for stdin | 2025-03-13 | +| [0003](0003-package-layout.md) | Layer the code as cmd → processor → yamlparser → k8s | 2025-03-17 | +| [0004](0004-approval-testing.md) | Pin behaviour with golden (approval) tests | 2025-03-18 | +| [0005](0005-run-entry-point-seam.md) | Expose the CLI as an in-process `Run(args, stdin, stdout, stderr) int` | 2026-08-02 | +| [0006](0006-conventional-commits-and-releases.md) | Automate releases from Conventional Commits | 2026-08-06 |