Skip to content

docs: P1 backlog — converge dev-stack duplication, unify gate and SBOM-upload naming#507

Merged
haksungjang merged 1 commit into
mainfrom
docs/backlog-p1
Jul 18, 2026
Merged

docs: P1 backlog — converge dev-stack duplication, unify gate and SBOM-upload naming#507
haksungjang merged 1 commit into
mainfrom
docs/backlog-p1

Conversation

@haksungjang

Copy link
Copy Markdown
Contributor

Summary

The three P1 items from the 2026-07 documentation benchmark review (drift-prone duplication and split vocabulary).

1. Dev-stack boot steps: last duplication converged

contributor-guide/getting-started.md re-stated the dev-stack bring-up independently — and had already drifted: it skipped the env-file and schema-migration steps, so following it verbatim left the health-gated worker blocking up. It now delegates to [Quickstart steps 1–3] and keeps only the contributor-specific extras (logs, ports, host-local backend/frontend variants). This was the last of the three duplicated boot sequences (quickstart was made canonical and docker-compose delegated in #505).

2. Terminology: "policy gate" → "build gate"

The same mechanism was named differently per page (analysis-types/faq said policy gate; github-actions/scans/triage said build gate). Unified to build gate across current docs. Deliberately untouched:

  • the glossary alias and the projects.md reconciliation sentence ("also called the policy gate") — kept so the old name still resolves;
  • release notes (historical records);
  • code identifiers (POST …/policy-gate, policy_gate_failed).

Renamed headings carry their old anchors explicitly ({#gate-detail}, {#build--policy-gate}, KO mirror), so no inbound link breaks.

3. Naming: one feature name for SBOM upload

The upload feature went by four names ("Received SBOMs (uploaded)", "Upload an SBOM", "uploaded SBOM", API sbom-ingest). Section titles and link texts now say SBOM upload (KO: SBOM 업로드); the how-to page keeps its task-style title ("Upload an SBOM"), descriptive uses of "an uploaded SBOM" as a noun phrase remain, and the #received-sboms-uploaded anchor is preserved.

Verification

  • Docusaurus EN+KO build green — 0 broken links/anchors (all renamed headings keep explicit anchors)
  • docs-uat extract green — 201 steps, ids/KO parity unchanged
  • ko-style lint S1/S2/S3 all 0

Docs-only change — CI checks will skip; needs an --admin merge per repo convention.

…M-upload naming

Three P1 items from the 2026-07 docs benchmark review:

- contributor-guide/getting-started: replace the re-stated dev-stack
  boot steps with a delegation to Quickstart steps 1-3. The local copy
  had already drifted: it skipped the env-file and schema-migration
  steps, so following it verbatim left the health-gated worker blocking
  'up'. Last of the three duplicated boot sequences (the other two were
  converged in #505).
- Terminology: 'policy gate' -> 'build gate' across current docs
  (analysis-types, faq, notifications, github-actions, env-variables
  heading, policy-design, comparison). The glossary alias and the
  projects.md reconciliation sentence stay; release notes stay as
  historical records; code identifiers (policy-gate API path,
  policy_gate_failed enum) are untouched. Renamed headings keep their
  old anchors explicitly so no inbound link breaks.
- Naming: the SBOM-upload feature is now called 'SBOM upload' in section
  titles and link texts ('Received SBOMs' / 'uploaded SBOM' variants
  unified); the scans.md anchor #received-sboms-uploaded is preserved.

EN and KO mirrors updated together. Docusaurus EN+KO build green,
docs-uat extract 201 steps, ko-style S1/S2 0.
@haksungjang
haksungjang merged commit adad1f1 into main Jul 18, 2026
25 checks passed
@haksungjang
haksungjang deleted the docs/backlog-p1 branch July 18, 2026 15:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant