docs: design generated wiki stale purge
This commit is contained in:
@@ -0,0 +1,153 @@
|
|||||||
|
# Generated Wiki Stale Purge Design
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Add an explicit bulk purge path for generated NodeBB wiki pages that have become
|
||||||
|
stale after generator output changes, such as topdata visibility rules hiding
|
||||||
|
previously generated pages.
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
The topdata wiki deployer already owns generated page state through
|
||||||
|
`.cache/wiki/.wiki_deploy_manifest.json`. It currently recognizes stale
|
||||||
|
generated pages that remain in the deploy manifest but no longer exist in the
|
||||||
|
current generated wiki output. Existing stale policies can either report those
|
||||||
|
pages or archive them by rewriting their managed content.
|
||||||
|
|
||||||
|
That is not sufficient when the stale generated wiki topics should be removed
|
||||||
|
from NodeBB entirely. The Westgate Wiki plugin already treats a normal wiki topic
|
||||||
|
delete as an irreversible purge, so the deployer should use NodeBB's explicit
|
||||||
|
topic purge API when the operator asks for destructive generated-page cleanup.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
### In Scope
|
||||||
|
|
||||||
|
- Add `purge` as an explicit stale policy for topdata wiki deployment.
|
||||||
|
- Plan purge candidates only from generated page entries already tracked in the
|
||||||
|
wiki deploy manifest.
|
||||||
|
- Purge the exact tracked NodeBB topic for each stale generated page.
|
||||||
|
- Report purge counts in dry-run and live deploy output.
|
||||||
|
- Remove successfully purged page entries from the deploy manifest so later
|
||||||
|
deploys do not repeatedly target removed topics.
|
||||||
|
- Allow release automation to opt into purge through the existing stale-policy
|
||||||
|
environment variable path.
|
||||||
|
- Update toolkit and module documentation for the destructive cleanup mode.
|
||||||
|
|
||||||
|
### Out Of Scope
|
||||||
|
|
||||||
|
- Purging manually-authored NodeBB wiki pages.
|
||||||
|
- Discovering purge candidates by namespace browsing, title, slug, or wiki
|
||||||
|
search.
|
||||||
|
- Adding a soft-delete or restore workflow for stale generated wiki pages.
|
||||||
|
- Changing the Westgate Wiki plugin delete behavior.
|
||||||
|
- Adding a separate stale cleanup command outside `deploy-wiki`.
|
||||||
|
|
||||||
|
## Operator Interface
|
||||||
|
|
||||||
|
The existing `deploy-wiki` stale-policy surface gains a third explicit policy:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./deploy-wiki.sh --dry-run --stale-policy purge
|
||||||
|
./deploy-wiki.sh --stale-policy purge
|
||||||
|
```
|
||||||
|
|
||||||
|
Release automation may use the same policy through:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
SOW_MODULE_WIKI_DEPLOY_STALE_POLICY=purge
|
||||||
|
```
|
||||||
|
|
||||||
|
`purge` remains opt-in. Existing `report` and `archive` behavior remain
|
||||||
|
unchanged.
|
||||||
|
|
||||||
|
## Purge Eligibility
|
||||||
|
|
||||||
|
A page may be purged only when all of these are true:
|
||||||
|
|
||||||
|
1. The page exists in `.cache/wiki/.wiki_deploy_manifest.json`.
|
||||||
|
2. The page is absent from the current generated wiki page set in the deploy
|
||||||
|
scope.
|
||||||
|
3. The deploy manifest entry has the tracked NodeBB topic id required to call
|
||||||
|
the topic purge API.
|
||||||
|
|
||||||
|
The deployer must not search NodeBB for candidate pages when purging stale
|
||||||
|
generated output. It must not purge pages that are currently generated. It must
|
||||||
|
not purge pages that only exist as manually-authored NodeBB wiki content.
|
||||||
|
|
||||||
|
If a stale manifest entry has no topic id, purge planning fails clearly instead
|
||||||
|
of guessing a remote target.
|
||||||
|
|
||||||
|
## Deploy Flow
|
||||||
|
|
||||||
|
Stale planning stays inside the existing `deploy-wiki` deploy plan:
|
||||||
|
|
||||||
|
- `report` increments the stale count only.
|
||||||
|
- `archive` produces the existing archive post-update action.
|
||||||
|
- `purge` produces a destructive topic-purge action for the manifest entry's
|
||||||
|
tracked topic id.
|
||||||
|
|
||||||
|
Dry runs calculate the same stale and purge counts as live runs but do not call
|
||||||
|
NodeBB and do not mutate the deploy manifest.
|
||||||
|
|
||||||
|
Live purge execution calls NodeBB's topic purge API for each planned stale
|
||||||
|
generated page. NodeBB auth, permission, missing-topic, or transport failures
|
||||||
|
abort the deploy with the failing generated page id and remote topic context.
|
||||||
|
|
||||||
|
## Manifest State
|
||||||
|
|
||||||
|
Archive retains stale entries in the manifest because the archived post remains
|
||||||
|
managed remotely.
|
||||||
|
|
||||||
|
Purge removes each successfully purged page entry from the next deploy manifest.
|
||||||
|
This records that the generated page no longer has a managed remote NodeBB topic
|
||||||
|
and prevents later deploys from attempting to purge an already removed topic.
|
||||||
|
|
||||||
|
If a purge deployment fails partway through, only state written after the
|
||||||
|
existing deploy execution succeeds should reach the manifest. A later rerun may
|
||||||
|
retry the stale manifest entries still present, matching the deployer's current
|
||||||
|
all-or-error manifest persistence behavior.
|
||||||
|
|
||||||
|
## Reporting And Validation
|
||||||
|
|
||||||
|
Toolkit deploy output gains a `purged` count alongside the existing `stale` and
|
||||||
|
`archived` counts. Dry-run summaries must make the destructive plan visible
|
||||||
|
before a live purge run.
|
||||||
|
|
||||||
|
`purge` must be accepted wherever stale policy is validated:
|
||||||
|
|
||||||
|
- project config stale-page settings
|
||||||
|
- `deploy-wiki --stale-policy`
|
||||||
|
- module release wrapper validation for
|
||||||
|
`SOW_MODULE_WIKI_DEPLOY_STALE_POLICY`
|
||||||
|
|
||||||
|
Unsupported stale policy values must keep failing early with clear error text.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
Toolkit tests should cover:
|
||||||
|
|
||||||
|
- stale policy validation accepts `purge`
|
||||||
|
- unsupported stale policy values still fail
|
||||||
|
- dry-run purge reports stale and purged counts without calling NodeBB or
|
||||||
|
changing the manifest
|
||||||
|
- live purge calls the NodeBB topic purge endpoint for a stale tracked generated
|
||||||
|
topic
|
||||||
|
- live purge removes the manifest entry after success
|
||||||
|
- purge refuses a stale manifest entry without a tracked topic id
|
||||||
|
- current generated pages are never purge candidates
|
||||||
|
- archive/report behavior remains unchanged
|
||||||
|
|
||||||
|
Module wrapper/docs coverage should verify:
|
||||||
|
|
||||||
|
- release stale-policy validation accepts `purge`
|
||||||
|
- docs describe purge as destructive, generated-manifest-scoped cleanup
|
||||||
|
|
||||||
|
## Compatibility
|
||||||
|
|
||||||
|
Default behavior remains `report`. Existing archive cleanup remains available and
|
||||||
|
unchanged. The destructive purge path activates only when the operator selects
|
||||||
|
`purge`.
|
||||||
|
|
||||||
|
The purge boundary is intentionally stricter than normal page adoption logic:
|
||||||
|
generated manifest state authorizes the target; NodeBB discovery never does.
|
||||||
Reference in New Issue
Block a user