129 lines
8.3 KiB
Markdown
129 lines
8.3 KiB
Markdown
---
|
|
phase: quick-260928-lf2
|
|
plan: 01
|
|
subsystem: docs
|
|
status: complete
|
|
tags: [docs, readme, modules, claude-md]
|
|
requires: []
|
|
provides:
|
|
- "18 app-agnostic module READMEs built from the real exported API"
|
|
- "Generic SummerCMS (Go) framework root README with an 18-row modules table"
|
|
- "CLAUDE.md Documentation rule keeping module READMEs current"
|
|
affects: [README.md, CLAUDE.md, modules/*/README.md]
|
|
tech-stack:
|
|
added: []
|
|
patterns:
|
|
- "Module README template: H1, summary, import line, Overview, Features, Usage, API reference, optional Configuration/CLI commands, Dependencies, Testing"
|
|
key-files:
|
|
created: []
|
|
modified:
|
|
- README.md
|
|
- CLAUDE.md
|
|
- modules/backpack/README.md
|
|
- modules/boardwalk/README.md
|
|
- modules/bonfire/README.md
|
|
- modules/bouncer/README.md
|
|
- modules/cabana/README.md
|
|
- modules/compass/README.md
|
|
- modules/festival/README.md
|
|
- modules/fetchguard/README.md
|
|
- modules/lagoon/README.md
|
|
- modules/pact/README.md
|
|
- modules/party/README.md
|
|
- modules/phrasebook/README.md
|
|
- modules/postcard/README.md
|
|
- modules/surf/README.md
|
|
- modules/tide/README.md
|
|
- modules/towel/README.md
|
|
- modules/wire/README.md
|
|
- modules/wristband/README.md
|
|
decisions:
|
|
- "Root README quick start was verified end to end against a throwaway Postgres 16 container; it states the extra config the example needs instead of hiding it"
|
|
- "Known issues found while verifying (example body limits, pl-PL locale, stale generated main.go) are documented in the root README and left unfixed, since this is a docs-only task"
|
|
- "Module README commits were split per agent batch (three commits), as the approved design allows"
|
|
metrics:
|
|
completed: 2026-09-28
|
|
tasks: 3
|
|
files: 20
|
|
actuals:
|
|
tokens: 31800
|
|
tasks: 3
|
|
commits: 5
|
|
plan_head_before: cc584e906e2a67f7e04b979ac632d6e24c21011d
|
|
plan_head_after: fafb12ff02f4693d0380f7fd3ab9f8d32791ee8d
|
|
commits: 5
|
|
---
|
|
|
|
# Phase quick-260928-lf2 Plan 01: Module READMEs, Generic Root README and Documentation Rule Summary
|
|
|
|
The 18 module READMEs were rewritten from each package's real exported API. The root README is now a generic framework README whose quick start was verified against a real Postgres. CLAUDE.md now requires module README updates in the same change as any module API, config, CLI or dependency change.
|
|
|
|
## Commits
|
|
|
|
| Task | Commit | Subject |
|
|
|------|--------|---------|
|
|
| 1 (batch A) | 1bd3494 | docs(modules): rewrite cabana, wire, towel, festival, compass, backpack READMEs |
|
|
| 1 (batch B) | 3142aeb | docs(modules): rewrite lagoon, tide, pact, party, boardwalk, fetchguard READMEs |
|
|
| 1 (batch C) | aaa892f | docs(modules): rewrite wristband, bouncer, surf, bonfire, phrasebook, postcard READMEs |
|
|
| 2 | 70d3c39 | docs: generic root README |
|
|
| 3 | fafb12f | docs(claude): require module README updates |
|
|
|
|
No commit carries a co-author or other attribution trailer.
|
|
|
|
## What was done
|
|
|
|
- **Task 1** (done earlier, three batch commits): 18 module READMEs follow the locked template and name no consuming application. Every package-qualified identifier resolves through go doc.
|
|
- **Task 2:** The root `README.md` covers the nine outline items: what SummerCMS is, key concepts, requirements, a quick start on `examples/hello`, the repository layout, the modules table, module path plus local replace, development commands, and design notes. The modules table has 18 rows, and each purpose cell matches that module README's summary sentence exactly (checked by script). The notes section links only the four app-neutral notes.
|
|
- **Task 3:** `## Documentation` sits between `## Commit rules` and the first `<!-- GSD:project-start -->` marker. It has four bullets: the same-change README update rule, the standard structure plus a modules-table row for new modules, no consuming-application names, and go doc identifier checks. The change only adds lines (7 insertions, 0 deletions).
|
|
|
|
## Quick start verification
|
|
|
|
Every command in the quick start was confirmed before it was written:
|
|
- `go run ./cmd/summer --help` and `./bin/hello --help` list the quoted commands.
|
|
- `summer build` in `examples/hello` produces `bin/hello`.
|
|
- `greeter:hello` and `key:generate` run without a database.
|
|
- A throwaway `postgres:16-alpine` container, with a database created with ICU `pl-PL`, was used for the rest. With `SUMMER_DATABASE__DSN`, `SUMMER_APP__KEY` and `SUMMER_STORAGE__UPLOADS__BUCKET_URL=mem://` set, and a temporary `config/http.yaml` holding the body limits, these all succeeded: `migrate`, `migrate:status`, `route:list`, and `serve --addr` (`GET /items/1` returned `{"id":1}`).
|
|
|
|
Afterwards the temporary config file was removed, the regenerated `main.go` was restored and the container was stopped. `git status --porcelain examples/` is empty.
|
|
|
|
## Checks
|
|
|
|
| Check | Result |
|
|
|-------|--------|
|
|
| Forbidden-name grep over README.md and modules/*/README.md | NAMES OK |
|
|
| Root README content (TABLE/MISSING/LAYOUT) | ROOT OK |
|
|
| Relative links in README.md and all module READMEs | LINKS OK |
|
|
| Module README structure (title, import, section order) | STRUCTURE OK |
|
|
| Package-qualified identifiers resolve via go doc | IDENTS OK |
|
|
| `scripts/check-phase10.2.sh --readmes` and `--status` | pass |
|
|
| `git status --porcelain examples/` empty | pass |
|
|
| CLAUDE.md section placement, additions only | CLAUDE OK |
|
|
| `go vet ./...`, `go test ./...`, no `.go` changes since cc584e9, no co-author trailer | SANITY OK |
|
|
|
|
The Task 1 executors reported that the plain `](` link check gives false positives on Go generics inside code blocks. The plan's check excludes `(`, `#` and whitespace from the target, and it reported no false positives on the final files.
|
|
|
|
## Deviations from Plan
|
|
|
|
- **Quick start content.** The plan outline puts `serve` and `migrate` right after `summer build`. In practice they also need `app.key`, an uploads bucket URL, numeric `http.body_limits` values from a config file and an ICU `pl-PL` database. The README states these requirements and adds a Known issues subsection rather than leaving out steps. No Go code or example config was changed.
|
|
- **Commits on master.** They were made on `master`. The project config uses `branching_strategy: none` and no worktrees, and Task 1 and the orchestrator instructions follow the same practice.
|
|
|
|
## Known Stubs
|
|
|
|
None.
|
|
|
|
## Follow-ups (not fixed; docs-only task)
|
|
|
|
1. **`examples/hello` lacks `http.body_limits` config.** surf fails at boot with `surf: config http.body_limits.default_bytes is required`, which breaks `serve`, `route:list` and the example's `TestTypedItemRoute` (confirmed: `cd examples/hello && go test ./...` fails there). The root `go test ./...` does not cover the example module, so it stays green. Fix: add `examples/hello/config/http.yaml` with `default_bytes`/`upload_bytes`, then drop step 2 and the first Known issues bullet from the root README.
|
|
2. **The `SUMMER_` env overlay cannot set numeric keys that surf reads.** `SUMMER_HTTP__BODY_LIMITS__DEFAULT_BYTES=1048576` is rejected with `must be numeric, got string`. Either compass should coerce these values or surf should parse numeric strings.
|
|
3. **surf validates `http.body_limits.upload_bytes` but never applies it.**
|
|
4. **lagoon hardcodes an application locale:** `lagoon.CheckLocale` requires ICU `pl-PL` (`requiredICULocale` in `modules/lagoon/connection.go`). This should be configurable, with `pl-PL` as the application's setting.
|
|
5. **wristband hardcodes application values:** `wristband.DefaultOptions().Resource` is an application URL, and the scopes and `/oauth/mcp/*` paths are fixed. These should come from options or config.
|
|
6. **The committed `examples/hello/main.go` is stale.** It predates the generator's `surf.RouteListCommand` and `cabana.RuntimeCommands` wiring, so `summer build` and the example's `TestBuiltBinary*` tests leave it modified. Fix: regenerate and commit it.
|
|
7. **`key:generate` prints a `✓ ` prefix before the key,** so `export SUMMER_APP__KEY=$(./bin/hello key:generate)` produces an invalid key. The README tells readers to copy the value. Consider printing the bare key to stdout.
|
|
8. **Application repository README:** the removed application-specific run steps (database setup, admin path, cutover status) should be checked against the application repository's own README. It was not edited here, per the plan.
|
|
|
|
## Self-Check: PASSED
|
|
|
|
- FOUND: README.md, CLAUDE.md, all 18 modules/*/README.md
|
|
- FOUND commits: 1bd3494, 3142aeb, aaa892f, 70d3c39, fafb12f
|