77 lines
4.9 KiB
Markdown
77 lines
4.9 KiB
Markdown
# Post-Port Documentation Verification Checklist
|
|
|
|
## Purpose
|
|
|
|
Use this checklist after a documentation-porting slice updates inherited boilerplate docs for the current repository state. The goal is to confirm that ported prose follows `docs/porting-guide.md`, preserves known runtime identifiers, and ties any remaining legacy wording back to the Porting Docs baseline instead of leaving reviewers to guess.
|
|
|
|
This checklist is documentation-only. It does not authorize runtime package renames, route extraction, queue-name changes, database identifier changes, or new package-manager behavior.
|
|
|
|
## Source Evidence
|
|
|
|
Review the ported document against these sources before marking a documentation port complete:
|
|
|
|
- `docs/porting-guide.md` for the canonical rename/replace map, do-not-replace rules, package-manager wording, hybrid runtime status, and manual E2E policy.
|
|
- `.tc/baselines/porting-docs/baseline-health.md` for the Porting Docs baseline report, successful non-E2E gate fingerprints, and documentation inventory counts.
|
|
- `package.json` for the current root package name, pinned `packageManager` value (`pnpm@10.33.0`), and available static verification scripts.
|
|
- The document being ported plus any source document it cites as evidence.
|
|
|
|
## Checklist
|
|
|
|
- [ ] Product prose uses generic boilerplate wording where it describes this repository, while historical upstream references remain clearly historical.
|
|
- [ ] Package-manager examples use Corepack and pinned `pnpm@10.33.0` wording where setup or local commands are described.
|
|
- [ ] Current runtime wording says `apps/web/app` remains authoritative for web source and root scripts remain command entrypoints unless a later verified extraction changed that fact.
|
|
- [ ] Workspace boundaries are described precisely as runtime-wired, partially runtime-wired, skeleton-only, source-only, plugin-candidate, or removal/review targets.
|
|
- [ ] Database wording stays aligned with PostgreSQL through Prisma, `packages/db` as the server-side Prisma client boundary, and root `prisma/` schema/migrations where relevant.
|
|
- [ ] Transactional mail wording names the Mailjet boundary when describing active mail behavior.
|
|
- [ ] Worker, queue, Redis, Docker smoke, Gitea CI, and deployment wording matches the current README and does not imply unsupported production automation.
|
|
- [ ] Existing runtime identifiers are preserved when they are package names, queue names, environment variables, Prisma paths, seeded local accounts, third-party dependency names, public route shapes, or historical decision/report references.
|
|
- [ ] Remaining legacy terms are classified in prose or review notes as intentionally protected identifiers, historical references, or drift to fix in the same slice.
|
|
- [ ] No new `TODO`, `TBD`, `FIXME`, or `XXX` marker is introduced unless the slice explicitly permits that exact backlog marker.
|
|
|
|
## Backlog Markers
|
|
|
|
Use explicit backlog wording only when the behavior is not yet implemented or verified. Backlog entries should not read like runtime guarantees.
|
|
|
|
- Package-manager scaffold-create path: future work should verify and document whether a `pnpm create` scaffold flow exists for this boilerplate. Until that work lands, documentation may mention this as backlog only and must not claim that the create path is available, supported, or CI-verified.
|
|
|
|
## Static Verification
|
|
|
|
Run task-scoped static checks for the files changed by the documentation slice. At minimum, confirm the ported file is non-empty and that the post-port checklist or guide anchors still exist:
|
|
|
|
```sh
|
|
test -s docs/porting-verification.md
|
|
test -s docs/porting-guide.md
|
|
grep -n "^## Checklist" docs/porting-verification.md
|
|
grep -n "pnpm create" docs/porting-verification.md
|
|
grep -n "^## Verification" docs/porting-guide.md
|
|
```
|
|
|
|
Use the Porting Docs baseline gate when validating the broader documentation-porting baseline:
|
|
|
|
```sh
|
|
pnpm run verify:porting-docs-baseline
|
|
```
|
|
|
|
The Porting Docs baseline report also records these established non-E2E gates from for comparison:
|
|
|
|
```sh
|
|
pnpm run typecheck
|
|
pnpm run lint
|
|
pnpm exec vitest run scripts/check-api-inventory.test.ts apps/web/app/application/featureManifests.test.ts
|
|
```
|
|
|
|
For CI/deployment prose, the relevant static scripts include:
|
|
|
|
```sh
|
|
pnpm run verify:ci-baseline
|
|
pnpm run verify:gitea-ci-workflow
|
|
```
|
|
|
|
Do not replace scoped documentation checks with broad browser or end-to-end runs during auto-mode execution.
|
|
|
|
## Manual-Only Checks
|
|
|
|
Browser and E2E checks stay manual unless explicitly approved for the exact run in the current session. Documentation slices may describe the manual scenario to review, but auto-mode task verification should not launch Playwright, Cypress, browser automation, or other live E2E flows without that approval.
|
|
|
|
Manual reviewers should sample rendered Markdown, links, and any screenshots or UI references after static checks pass. If a documentation update changes command examples, verify the commands against `package.json` and the relevant baseline report before presenting them as supported behavior.
|