docs(11.1-03): complete the Setup, Architecture, Plugins and Console docs plan
This commit is contained in:
Jakub Zych
@@ -0,0 +1,246 @@
|
||||
---
|
||||
phase: 11.1-summercms-documentation-for-humans-and-ai-agents
|
||||
plan: 03
|
||||
subsystem: docs
|
||||
tags: [docs, wintercms, concept-map, examples, console, architecture, plugins]
|
||||
|
||||
requires:
|
||||
- phase: 11.1-02
|
||||
provides: "identifier, link, command, forbidden, fence and callout checkers; the theme; docs:serve; scripts/check-phase11.1.sh"
|
||||
- phase: 11.1-01
|
||||
provides: "internal/docsite generator, docs:build, docs:sync, src= snippet extraction and bonfire ExampleCall"
|
||||
provides:
|
||||
- "docs/setup: introduction, installation (rewritten), configuration, coming-from-wintercms"
|
||||
- "docs/architecture: introduction, go-modules-and-workspaces, application-lifecycle, request-lifecycle"
|
||||
- "docs/plugins: registration, scheduling, extending, testing"
|
||||
- "docs/console: introduction, setup-and-maintenance, scaffolding, writing-commands, utilities"
|
||||
- "site.yaml sections setup, architecture, plugins, console, api"
|
||||
- "Examples: party ExamplePlugin (with BlogPlugin in example_plugin_test.go), backpack ExampleApp_Publish, pact ExampleHasSchedule, festival ExampleBus_Fire, towel ExampleWithLocale, bonfire ExampleCatalog"
|
||||
- "cmd/summer TestDocsRequiredPages with 18 required page URLs"
|
||||
affects: [11.1-04, 11.1-05, 11.1-06]
|
||||
|
||||
estimate_ref: "tokens 100000, tasks 3, confidence low"
|
||||
actuals:
|
||||
tokens: 23900
|
||||
tasks: 3
|
||||
commits: 4
|
||||
plan_head_before: f77b1d868890ed8e2762d71e6a64c94274615edf
|
||||
plan_head_after: 8254fb91a92ae4a297ed536f8dac6145caa55372
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "A plugin type that a page shows in full lives in its own example_plugin_test.go and is referenced as a whole-file src= fence; the Example that exercises it is a separate #Example fence"
|
||||
- "Descriptions containing ': ' are double-quoted in frontmatter (goccy/go-yaml rejects them unquoted)"
|
||||
- "Commands in docs are written as summer <name> or ./bin/acme <name> so the command checker verifies them; ./bin/<app> placeholders are never used because the checker cannot see them"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- docs/setup/introduction.md
|
||||
- docs/setup/configuration.md
|
||||
- docs/setup/coming-from-wintercms.md
|
||||
- docs/architecture/introduction.md
|
||||
- docs/architecture/go-modules-and-workspaces.md
|
||||
- docs/architecture/application-lifecycle.md
|
||||
- docs/architecture/request-lifecycle.md
|
||||
- docs/plugins/registration.md
|
||||
- docs/plugins/scheduling.md
|
||||
- docs/plugins/extending.md
|
||||
- docs/plugins/testing.md
|
||||
- docs/console/introduction.md
|
||||
- docs/console/setup-and-maintenance.md
|
||||
- docs/console/scaffolding.md
|
||||
- docs/console/writing-commands.md
|
||||
- docs/console/utilities.md
|
||||
- modules/party/example_test.go
|
||||
- modules/party/example_plugin_test.go
|
||||
- modules/backpack/example_test.go
|
||||
- modules/pact/example_test.go
|
||||
- modules/festival/example_test.go
|
||||
- modules/towel/example_test.go
|
||||
- .planning/todos/pending/bonfire-duplicate-command-names.md
|
||||
modified:
|
||||
- docs/site.yaml
|
||||
- docs/index.md
|
||||
- docs/setup/installation.md
|
||||
- modules/bonfire/example_test.go
|
||||
- cmd/summer/docs_test.go
|
||||
|
||||
key-decisions:
|
||||
- "The Plugin.php-in-Go section shows the whole modules/party/example_plugin_test.go file, because a Go Example body cannot declare the four party.Plugin methods; ExamplePlugin is shown separately as the plan requires"
|
||||
- "Hand-written Go fences are never used: a GORM-callback sketch and a Commands() sketch were replaced by prose rather than shipping unverified Go"
|
||||
- "Pages describe bonfire as it is: command names are not checked for duplicates. The gap is logged as a todo; bonfire is not changed in this plan"
|
||||
- "serve's default --addr (:8080) is documented as listening on every interface, with loopback shown in every example"
|
||||
|
||||
patterns-established:
|
||||
- "requiredPages in cmd/summer/docs_test.go is the list each content plan appends to"
|
||||
- "Example files use package <m>_test and the neutral acme.* plugin IDs"
|
||||
|
||||
requirements-completed: [DOCS-01, DOCS-04, DOCS-06]
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "Coming from WinterCMS maps WinterCMS concepts to 50 distinct checked pkg.Ident spans, lists what is not provided and shows Plugin.php next to a verified Go plugin"
|
||||
requirement: DOCS-06
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "cmd/summer/docs_test.go#TestDocsTree"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "modules/party/example_test.go#ExamplePlugin"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "Setup, Architecture, Plugins and Console sections are in the sidebar in that order before API reference, and every page of this plan builds as .html and .md"
|
||||
requirement: DOCS-01
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "cmd/summer/docs_test.go#TestDocsRequiredPages"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "cmd/summer/docs_test.go#TestDocsAIOutputsInSync"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "cmd/summer/docs_test.go#TestDocsBuildRealTree"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "Every Go fence in the new pages is a src= copy of an Example or test declaration that go test runs"
|
||||
requirement: DOCS-04
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "modules/backpack/example_test.go#ExampleApp_Publish"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "modules/pact/example_test.go#ExampleHasSchedule"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "modules/festival/example_test.go#ExampleBus_Fire"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "modules/towel/example_test.go#ExampleWithLocale"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "modules/bonfire/example_test.go#ExampleCatalog"
|
||||
status: pass
|
||||
- kind: other
|
||||
ref: "go run ./cmd/summer docs:build --check"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D4
|
||||
description: "Console pages name only commands that exist; no page names a consuming application; examples bind loopback"
|
||||
requirement: DOCS-01
|
||||
verification:
|
||||
- kind: other
|
||||
ref: "scripts/check-phase11.1.sh --docs and --forbidden"
|
||||
status: pass
|
||||
- kind: other
|
||||
ref: "! grep -rn '0\\.0\\.0\\.0' docs/setup docs/console"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D5
|
||||
description: "Pages read in WinterCMS docs tone and are useful to a WinterCMS developer"
|
||||
verification: []
|
||||
human_judgment: true
|
||||
rationale: "Backstop truth in the plan: tone and usefulness are a reader's judgment"
|
||||
|
||||
duration: 15min
|
||||
completed: 2026-09-30
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 11.1 Plan 03: Framework content A (Setup, Architecture, Plugins, Console) Summary
|
||||
|
||||
**Sixteen new or rewritten guide pages cover installation to serve, a WinterCMS concept map with 50 checked identifiers, the binary and request lifecycles, plugin registration, scheduling, extending and testing, and every `summer` and application command. Each Go block on them is a copy of an Example that `go test` runs.**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** about 15 min
|
||||
- **Started:** 2026-09-30T20:03:31Z
|
||||
- **Completed:** 2026-09-30T20:18Z
|
||||
- **Tasks:** 3
|
||||
- **Files modified:** 28
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- `docs/setup/coming-from-wintercms.md` has a 21-row concept table (WinterCMS, SummerCMS identifiers, module link), a "What is not provided" table (CMS pages, themes, components, AJAX and Snowboard, media manager, import/export, sorting, collections, behaviours, cache, session), and a "Plugin.php in Go" section with a PHP fence next to the verified Go plugin.
|
||||
- Architecture explains the single binary and headless model, the module map by concern, `summer` versus the application binary, go.mod `replace` and `go.work` workflows with `summer plugin:add`, the generated start-up sequence, Register-then-Boot, the typed container, `lagoon.OnDatabase`, and surf's wrapping order (read from `surf.Router.wrap`: CORS, recovery, locale, body limit, route middleware, constraints).
|
||||
- Plugins covers ID rules (from `pluginIDRe`), the capability interfaces, embedded config, lang and mail files, the scaffolded layout, schedule semantics and validation, leader election, `schedule:run --once` for cron, events with the three dispatch modes, services, optional dependencies, GORM callbacks and forking, and the test workflow including the ICU database requirement.
|
||||
- Console lists every runtime command with flags (migrations, key, serve, route:list, admin, queue, schedule, websockets), the seven commands `summer` delegates, what each `make:` command writes (from internal/build/artifact.go), the bonfire API for writing commands, and the parity and docs utilities with their flags and defaults.
|
||||
- Installation now walks from `go install` through `summer build`, the ICU database, `config/http.yaml`, `SUMMER_` variables with `<secret>` markers, `migrate`, `route:list` and `serve --addr 127.0.0.1:8080`, with the known issues as a `[!WARNING]` callout. Its ExampleCall section is kept.
|
||||
- `TestDocsRequiredPages` asserts all 18 required URLs load and build as `.html` and `.md`.
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1: Tracer, the concept map with a verified plugin example:** `d6003cd` (feat)
|
||||
2. **Task 2: Architecture and Plugins sections:** `1f8f5e1` (feat)
|
||||
3. **Task 3: Setup and Console sections:** `a896f3f` (feat)
|
||||
4. **Todo for the bonfire duplicate command name gap:** `8254fb9` (docs)
|
||||
|
||||
**Plan metadata:** the docs(11.1-03) commit that adds this file
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
See `key-files` in the frontmatter.
|
||||
|
||||
## Decisions Made
|
||||
|
||||
See `key-decisions` in the frontmatter.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] The plugin type could not live in the Example body**
|
||||
- **Found during:** Task 1
|
||||
- **Issue:** The plan's `#ExamplePlugin` fence shows only the Example body, and Go methods cannot be declared inside a function. The "Plugin.php in Go" section needs the four `party.Plugin` methods to be visible.
|
||||
- **Fix:** `BlogPlugin` and its methods are in `modules/party/example_plugin_test.go`, shown as a whole-file `src=` fence. `ExamplePlugin` in `example_test.go` uses it and is shown as the planned `#ExamplePlugin` fence.
|
||||
- **Files modified:** modules/party/example_plugin_test.go (one file beyond the plan's list)
|
||||
- **Commit:** d6003cd
|
||||
|
||||
**2. [Rule 1 - Bug] Frontmatter descriptions with a colon failed to parse**
|
||||
- **Found during:** Task 2
|
||||
- **Issue:** Four descriptions contained `: ` and goccy/go-yaml rejected them (`mapping value is not allowed in this context`).
|
||||
- **Fix:** Those description values are double-quoted.
|
||||
- **Commit:** 1f8f5e1
|
||||
|
||||
**3. [Rule 1 - Accuracy] Claims corrected against the code before commit**
|
||||
- A statement that duplicate command names fail at start-up was false (bonfire has no duplicate check). The page now describes the real behaviour, and the gap is logged in `.planning/todos/pending/bonfire-duplicate-command-names.md`.
|
||||
- Two hand-written Go fences (a GORM callback in Boot and a `Commands()` method) were replaced by prose, because Go fences in docs pages must be `src=` copies.
|
||||
- The `wire` description was rewritten from its README (HTML characters unescaped, no trailing newline, `[]` for nil lists, Carbon timestamps).
|
||||
|
||||
### Notes
|
||||
|
||||
- `registration.md` does not link the Console scaffolding page, because that page did not exist when Task 2 committed. It points at the `make:` commands in prose instead.
|
||||
- `gofmt -l modules/party` lists `registry_test.go`, which this plan did not touch.
|
||||
|
||||
**Total deviations:** 2 auto-fixed (1 blocking, 1 bug) and 1 set of accuracy corrections. **Impact:** none on scope.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None. The in-flight Phase 11 review edits (`modules/lagoon/transaction*.go`, the check-phase10/11 scripts and the Phase 11 review files) were never staged or touched. `go test -short ./...` was green at every commit with them in the tree.
|
||||
|
||||
## Verification
|
||||
|
||||
- `go vet ./...` and `go test -short ./...` are green.
|
||||
- All six new Examples and `ExampleCall` report `--- PASS`.
|
||||
- `TestDocsTree`, `TestDocsRequiredPages`, `TestDocsAIOutputsInSync` and `TestDocsBuildRealTree` pass. `docs:build` writes 40 pages.
|
||||
- `go run ./cmd/summer docs:build --check` reports no problems. `docs:sync` reports every snippet up to date.
|
||||
- `scripts/check-phase11.1.sh --docs` and `--forbidden` pass.
|
||||
- Every acceptance grep in the plan matches: 50 distinct identifiers on the concept map, 8 Architecture and Plugins pages, 4 Setup and 5 Console pages, `ICU_LOCALE` and the ExampleCall fence in installation.md, and no `0.0.0.0` in setup or console.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
Plan 11.1-04 can add the Backend, Database and Services sections between Plugins and Console in site.yaml, link the concept map rows to its new guide pages, and append its pages to `requiredPages`.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
All created files exist. Commits d6003cd, 1f8f5e1, a896f3f and 8254fb9 are in the log.
|
||||
@@ -9,4 +9,4 @@ area: summercms.go bonfire
|
||||
|
||||
Found while writing `docs/console/writing-commands.md` (Phase 11.1 plan 03). The page describes the current behaviour: names are not checked for duplicates, so keep commands in the plugin's own namespace.
|
||||
|
||||
Suggested fix: make `bonfire.NewRoot` fail with an error naming the duplicated command when two commands share a name. `bonfire.NewCatalog`, which the scheduler calls through, has no error return, so the generated `main` should build the root first (as it does today) and rely on that check. Update the bonfire README and the docs page in the same change (the D-13 docs rule). The API change is outside the docs phase boundary, so it is not made in Phase 11.1.
|
||||
Suggested fix: make `bonfire.NewRoot` fail with an error naming the duplicated command when two commands share a name. `bonfire.NewCatalog`, which the scheduler calls through, has no error return, but the generated `main` calls `bonfire.NewRoot` before it runs any command, so that check stops the binary before a duplicate can run. Update the bonfire README and the docs page in the same change (the D-13 docs rule). The API change is outside the docs phase boundary, so it is not made in Phase 11.1.
|
||||
|
||||
Reference in New Issue
Block a user