109 lines
3.8 KiB
Markdown
109 lines
3.8 KiB
Markdown
# Wiki Deployment Contract
|
|
|
|
## Scope
|
|
|
|
This contract governs the next focused phase after wrappers, config refactor,
|
|
logging, and topdata hardening:
|
|
|
|
- `toolkit/` owns `build-wiki` and `deploy-wiki`
|
|
- `module/` owns the consuming release workflow and operational configuration
|
|
|
|
This work is intentionally sequenced after topdata hardening because the wiki
|
|
pipeline consumes native topdata outputs and metadata.
|
|
|
|
## Current State
|
|
|
|
As of 2026-05-13:
|
|
|
|
- `build-wiki` exists
|
|
- `deploy-wiki` exists
|
|
- deployment targets NodeBB core `/api/v3`
|
|
- local deploy manifests and NodeBB topic mapping exist
|
|
- release automation in `module/scripts/release-all.sh` already runs wiki build
|
|
and deploy steps after release publication
|
|
- toolkit tests already cover dry-run behavior, topic creation, and manifest
|
|
writes
|
|
|
|
This means wiki deployment is no longer a greenfield feature. The next phase is
|
|
hardening, integration clarity, and operator experience.
|
|
|
|
## Deferred Until Current Priority Work Completes
|
|
|
|
Do not prioritize the following until wrappers/config/logging/topdata work is in
|
|
better shape:
|
|
|
|
- new NodeBB release-announcement posting flows
|
|
- broad wiki feature expansion
|
|
- unrelated formatting changes to generated page content
|
|
|
|
## Immediate Goals For The Wiki Phase
|
|
|
|
1. align wiki build/deploy logs with the structured logging contract
|
|
2. tighten config ownership for wiki defaults and category mappings
|
|
3. reduce residual hardcoded behavior that belongs in normalized config
|
|
4. improve release-flow clarity around dry-run, drift, create, and force modes
|
|
5. verify that topdata hardening does not silently change generated page identity
|
|
|
|
## Current Findings
|
|
|
|
- `deploy-wiki` already reads managed namespaces from effective config when the
|
|
caller does not specify them explicitly
|
|
- deploy manifest naming and edit-summary defaults still come from toolkit
|
|
defaults in `internal/project/effective.go`
|
|
- release orchestration already guards publication order correctly, but the
|
|
operator-facing logs are still more shell-oriented than the newer structured
|
|
`build-haks` presentation
|
|
- wiki deployment should be treated as a first-class operational command family,
|
|
not just a release-script tail step
|
|
|
|
## Immediate Plan
|
|
|
|
### Phase 1: Logging and UX parity
|
|
|
|
- add concise summaries for `build-wiki` and `deploy-wiki`
|
|
- surface counts for:
|
|
- pages collected
|
|
- creates
|
|
- updates
|
|
- skips
|
|
- drifted pages
|
|
- keep raw debug output available when diagnosis is needed
|
|
|
|
### Phase 2: Config clarity
|
|
|
|
- audit which wiki defaults should remain toolkit defaults versus explicit repo
|
|
config
|
|
- keep namespace/category ownership visible in effective config
|
|
- ensure deploy-manifest path and edit summary remain discoverable and easy to
|
|
override
|
|
|
|
### Phase 3: Release-flow hardening
|
|
|
|
- verify `module/scripts/release-all.sh` remains the authoritative release entry
|
|
point
|
|
- keep dry-run before live deploy
|
|
- ensure failure and drift messages are crisp and actionable
|
|
- make sure cache restore/save behavior is clearly documented and tested
|
|
|
|
### Phase 4: Regression verification after topdata hardening
|
|
|
|
- confirm topdata de-hardcoding does not break page IDs or manifest mapping
|
|
- confirm generated-page identity remains stable across unchanged inputs
|
|
|
|
## Testing Requirements
|
|
|
|
Add or expand tests for:
|
|
|
|
- app-layer output for `build-wiki` and `deploy-wiki`
|
|
- release-flow sequencing assumptions where wiki deploy must happen only after
|
|
release assets are published
|
|
- stable page identity and manifest mapping across repeated runs
|
|
- config-driven namespace selection and manifest path overrides
|
|
|
|
## Acceptance Criteria
|
|
|
|
- wiki build/deploy logs match the newer structured CLI standard
|
|
- wiki defaults and overrides are clearly represented in effective config
|
|
- release orchestration remains deterministic and easy to reason about
|
|
- topdata hardening does not regress page identity or deploy manifest behavior
|