From 0034a561ba5eade4ee6fb29436c76e4e34fa3a56 Mon Sep 17 00:00:00 2001 From: Elijah Duffy Date: Wed, 28 Oct 2026 15:12:58 -0700 Subject: [PATCH] refactor(docs)!: rename CLI binary to corestack-docs go install names binaries after the directory, so cmd/docs installed an ambiguous `docs` binary into $GOBIN that could clobber or be clobbered by other tools. Move it to cmd/corestack-docs, matching corestack-goose, and update goreleaser, CI, docs and usage text. Accepted ADRs keep their text and gain a dated rename note. BREAKING CHANGE: `go install go.auvem.com/corestack/cmd/docs@latest` stops resolving after the next tag; use cmd/corestack-docs. @v0.1.0 still installs the old `docs` binary. Co-Authored-By: Claude Opus 5.5 --- .gitea/workflows/docs-check.yml | 2 +- .goreleaser.yaml | 10 +++++----- AGENTS.md | 4 ++-- README.md | 12 ++++++------ cmd/{docs => corestack-docs}/main.go | 12 ++++++------ cmd/{docs => corestack-docs}/main_test.go | 0 ...ecked-format-for-adrs-and-implementation-plans.md | 2 ++ ...-root-module-and-nest-heavy-dependency-modules.md | 4 ++++ docs/adr/README.md | 2 +- docs/docs-format.md | 8 ++++---- 10 files changed, 31 insertions(+), 25 deletions(-) rename cmd/{docs => corestack-docs}/main.go (78%) rename cmd/{docs => corestack-docs}/main_test.go (100%) diff --git a/.gitea/workflows/docs-check.yml b/.gitea/workflows/docs-check.yml index 68ad004..2c0b3ff 100644 --- a/.gitea/workflows/docs-check.yml +++ b/.gitea/workflows/docs-check.yml @@ -12,4 +12,4 @@ jobs: with: go-version-file: go.mod cache: false - - run: go run ./cmd/docs check + - run: go run ./cmd/corestack-docs check diff --git a/.goreleaser.yaml b/.goreleaser.yaml index 82b9abb..577579e 100644 --- a/.goreleaser.yaml +++ b/.goreleaser.yaml @@ -1,10 +1,10 @@ version: 2 -project_name: docs +project_name: corestack-docs builds: - - id: docs - main: ./cmd/docs - binary: docs + - id: corestack-docs + main: ./cmd/corestack-docs + binary: corestack-docs env: - CGO_ENABLED=0 goos: [darwin, linux] @@ -14,7 +14,7 @@ builds: archives: - formats: [tar.gz] - name_template: "docs_{{ .Version }}_{{ .Os }}_{{ .Arch }}" + name_template: "corestack-docs_{{ .Version }}_{{ .Os }}_{{ .Arch }}" checksum: name_template: checksums.txt diff --git a/AGENTS.md b/AGENTS.md index 9b1ce1e..c95769d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ ## Commands - Check: `go build ./...`, `go vet ./...`, `go test -race ./...`, `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run ./...`; from the project root, run the TODO check below. - Generate: No code generation is configured; format with `gofmt -w .`. -- Documentation: `go run ./cmd/docs check`; create records with `go run ./cmd/docs new adr|plan "Title"`. This checker repository uses its local implementation as the source of truth. +- Documentation: `go run ./cmd/corestack-docs check`; create records with `go run ./cmd/corestack-docs new adr|plan "Title"`. This checker repository uses its local implementation as the source of truth. ## Scope and decisions - Before editing under a directory with its own AGENTS.md, read it. Scoped files: none currently; this root governs the repository, including nested Go modules unless nearer instructions override it. @@ -28,7 +28,7 @@ Go module `go.auvem.com/corestack`. -- Docs format (the spec `docs check` implements): `docs/docs-format.md`. +- Docs format (the spec `corestack-docs check` implements): `docs/docs-format.md`. - Decisions live in `docs/adr/`, plans in `docs/plans/`. Records are permanent; never rename them. - Add dependencies only to the module that needs them; heavy dependencies go in nested modules (see the [module-boundary ADR](/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md)). diff --git a/README.md b/README.md index 791a347..5c3984e 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,26 @@ # corestack go -Shared Go building blocks. Includes `docs`, a checker for architecture decision records (ADRs) and implementation plans; `page`, Bob keyset pagination; and `lifecycle`, a service and worker coordinator. +Shared Go building blocks. Includes `corestack-docs`, a checker for architecture decision records (ADRs) and implementation plans; `page`, Bob keyset pagination; and `lifecycle`, a service and worker coordinator. ## migrate [`migrate`](migrate/README.md) configures Goose providers for embedded SQL and Go migrations, with structured logging and Postgres startup locking. -## docs +## corestack-docs Install: ```sh -go install go.auvem.com/corestack/cmd/docs@latest +go install go.auvem.com/corestack/cmd/corestack-docs@latest ``` Use, from a repository root: ```sh -docs new adr "Use Example Queue for background jobs" # creates docs/adr/.md -docs new plan "Adopt Example Queue" # creates docs/plans/.md -docs check [--root DIR] # prints path:line: message; exit 1 on problems +corestack-docs new adr "Use Example Queue for background jobs" # creates docs/adr/.md +corestack-docs new plan "Adopt Example Queue" # creates docs/plans/.md +corestack-docs check [--root DIR] # prints path:line: message; exit 1 on problems ``` The format is specified in [docs/docs-format.md](docs/docs-format.md); that document is the complete rule set. Exit status is `0` when every record is valid, `1` when problems are reported and `2` for usage errors. diff --git a/cmd/docs/main.go b/cmd/corestack-docs/main.go similarity index 78% rename from cmd/docs/main.go rename to cmd/corestack-docs/main.go index 871355a..063e0fc 100644 --- a/cmd/docs/main.go +++ b/cmd/corestack-docs/main.go @@ -1,4 +1,4 @@ -// Command docs creates and checks ADR and plan records. See docs/docs-format.md. +// Command corestack-docs creates and checks ADR and plan records. See docs/docs-format.md. package main import ( @@ -12,8 +12,8 @@ import ( ) const usage = `usage: - docs new adr|plan "Title" - docs check [--root DIR] + corestack-docs new adr|plan "Title" + corestack-docs check [--root DIR] ` func main() { os.Exit(run(os.Args[1:], os.Stdout, os.Stderr, time.Now())) } @@ -32,13 +32,13 @@ func run(args []string, stdout, stderr io.Writer, now time.Time) int { } path, err := docs.New(".", args[1], args[2], now) if err != nil { - fmt.Fprintf(stderr, "docs: %v\n", err) + fmt.Fprintf(stderr, "corestack-docs: %v\n", err) return 1 } fmt.Fprintln(stdout, path) return 0 case "check": - fs := flag.NewFlagSet("docs check", flag.ContinueOnError) + fs := flag.NewFlagSet("corestack-docs check", flag.ContinueOnError) fs.SetOutput(stderr) root := fs.String("root", ".", "repository root") if err := fs.Parse(args[1:]); err != nil || fs.NArg() != 0 { @@ -49,7 +49,7 @@ func run(args []string, stdout, stderr io.Writer, now time.Time) int { } res, err := docs.Check(*root) if err != nil { - fmt.Fprintf(stderr, "docs: %v\n", err) + fmt.Fprintf(stderr, "corestack-docs: %v\n", err) return 1 } for _, p := range res.Problems { diff --git a/cmd/docs/main_test.go b/cmd/corestack-docs/main_test.go similarity index 100% rename from cmd/docs/main_test.go rename to cmd/corestack-docs/main_test.go diff --git a/docs/adr/20261023T214738672Z-adopt-a-checked-format-for-adrs-and-implementation-plans.md b/docs/adr/20261023T214738672Z-adopt-a-checked-format-for-adrs-and-implementation-plans.md index 4c2e052..ead4213 100644 --- a/docs/adr/20261023T214738672Z-adopt-a-checked-format-for-adrs-and-implementation-plans.md +++ b/docs/adr/20261023T214738672Z-adopt-a-checked-format-for-adrs-and-implementation-plans.md @@ -80,3 +80,5 @@ The format is specified in [docs-format](/docs/docs-format.md). It uses the MADR ## More Information MADR 4: https://adr.github.io/madr/. The specification is [docs-format](/docs/docs-format.md); the implementation lands in the same pull request that records this decision. + +Note (2026-10-28): the CLI was renamed from `docs` (`cmd/docs`) to `corestack-docs` (`cmd/corestack-docs`) so `go install` does not produce an ambiguous `docs` binary. The decision is unchanged. diff --git a/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md b/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md index 628c1ce..95511ad 100644 --- a/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md +++ b/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md @@ -49,3 +49,7 @@ This decision establishes the boundary before the planned packages are added. Th * Heavy-dependency and independently versioned packages avoid overlapping ownership of an import path with older root-module versions. * Each nested module needs its own dependency maintenance, checks, and prefixed release tags. That bookkeeping is reserved for packages that need the boundary. * Root-module consumers share version bumps even when only another core package changes. Moving a shipped root package into a nested module later still requires coordinated releases and consumer upgrades. + +## More Information + +Note (2026-10-28): `cmd/docs` was renamed to `cmd/corestack-docs`; read references to `cmd/docs` above as `cmd/corestack-docs`. The decision is unchanged. diff --git a/docs/adr/README.md b/docs/adr/README.md index 39e4fd5..5057daa 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -26,4 +26,4 @@ Use `write-adr` and `review-adr` when available: they guide reasoning while defe ## Reconcile before final review and merge -Compare the latest target branch plus the PR with the affected decisions and plans, not just the working branch's previous metadata. Update ADR implementation state and `implemented_by` with the real PR URL when delivery evidence supports it. Close finished plans with completion evidence and an Outcome; keep work active when scope remains. Never invent PR links, completed checks, owner acceptance, or delivery evidence. Run `docs check` using the pinned documentation command in the root AGENTS.md after reconciliation. +Compare the latest target branch plus the PR with the affected decisions and plans, not just the working branch's previous metadata. Update ADR implementation state and `implemented_by` with the real PR URL when delivery evidence supports it. Close finished plans with completion evidence and an Outcome; keep work active when scope remains. Never invent PR links, completed checks, owner acceptance, or delivery evidence. Run `corestack-docs check` using the pinned documentation command in the root AGENTS.md after reconciliation. diff --git a/docs/docs-format.md b/docs/docs-format.md index a4fc522..2396a77 100644 --- a/docs/docs-format.md +++ b/docs/docs-format.md @@ -1,6 +1,6 @@ # Docs format -This is the complete specification for architecture decision records (ADRs) and implementation plans checked by `docs check`. It is standalone: a file that follows this document is valid without running the tool. The words MUST, MUST NOT and MAY are used in their RFC 2119 sense. +This is the complete specification for architecture decision records (ADRs) and implementation plans checked by `corestack-docs check`. It is standalone: a file that follows this document is valid without running the tool. The words MUST, MUST NOT and MAY are used in their RFC 2119 sense. The ADR body uses the [MADR 4](https://adr.github.io/madr/) layout; `Consequences` is mandatory. The frontmatter, naming and cross-reference rules are specific to this format. @@ -135,7 +135,7 @@ Heading text is the raw source after the `#` markers, trimmed, with any closing ### 6.3 Placeholders -A record is invalid if it still contains the exact marker `{{docs:todo}}` anywhere outside code, including inside a frontmatter string value or list item (write it quoted there: `summary: "{{docs:todo}}"`). A list item equal to the marker reports only the marker error, not the format error for its key. `docs new` writes this marker into each field and section it leaves for you to fill; replace it with content. No other text is treated as a placeholder, so words like TODO or TBD are fine. To mention the marker itself, put it in inline or fenced code. +A record is invalid if it still contains the exact marker `{{docs:todo}}` anywhere outside code, including inside a frontmatter string value or list item (write it quoted there: `summary: "{{docs:todo}}"`). A list item equal to the marker reports only the marker error, not the format error for its key. `corestack-docs new` writes this marker into each field and section it leaves for you to fill; replace it with content. No other text is treated as a placeholder, so words like TODO or TBD are fine. To mention the marker itself, put it in inline or fenced code. ## 7. References and links @@ -156,9 +156,9 @@ URL: Always allowed in body prose only: in-page anchors (`#section`) and `mailto:` links. Any other scheme is rejected. -## 8. What `docs check` reports +## 8. What `corestack-docs check` reports -`docs check [--root DIR]` checks every record under `DIR` (default: the working directory) and prints one line per problem: +`corestack-docs check [--root DIR]` checks every record under `DIR` (default: the working directory) and prints one line per problem: ``` path:line: message -- 2.54.0