Skip to content

docs: correct the README's stale claims and document the staging workflow - #20

Open
LKSNDRTMLKV wants to merge 3 commits into
docs/licensing-navfrom
docs/readme-workflow
Open

docs: correct the README's stale claims and document the staging workflow#20
LKSNDRTMLKV wants to merge 3 commits into
docs/licensing-navfrom
docs/readme-workflow

Conversation

@LKSNDRTMLKV

Copy link
Copy Markdown
Member

Stacked on #19. The README describes a repository that no longer exists in several places, and one of those descriptions asserts a capability the tool has never had.

The claim that mattered

# Type-check + broken-link check
pnpm -r check

It is not a broken-link check and never was. A markdown link target is an opaque string to astro check, which is precisely why four [Licensing](/engine/licensing) links passed it and 404'd in production. A contributor reading this would reasonably believe links were covered, and stop looking — the same trap as a comment that describes a guard the code does not implement.

Corrected, and the four gates CI actually runs are now listed with what each one does.

Stale after recent work

  • The layout diagram listed a workspace-root public/brand/ directory that no longer exists — its copy step was publishing a duplicate favicon at a path nothing referenced — and omitted scripts/, which now holds two of the gates.
  • The Status section described CI as gating build + check. It runs six steps.
  • It pointed at the docs site under Design Principles, a section that was removed; the link survived only because a redirect happened to catch it. Now points at the pages that exist.
  • "What remains before public launch" listed the a11y pass and deployment, and predated the audit entirely.
  • The deploy explanation described pushing to main, which the new ruleset forbids.

Adds what was undocumented

staging exists and main is protected, and nothing in the repository said so. A contributor's first instinct is to branch off main and open a pull request against it — which now fails at the ruleset rather than at review. There is a short section describing the flow: work branches off staging, promotion is a separate stagingmain pull request, and main requires a pull request, squash-only merges, passing CI, and permits no bypass for anyone.

The Status section also now records what the audit found, in a sentence rather than a list, without pointing at the register — that lives in a private repository and public artefacts stay self-contained.

Verification: build green · 828 links resolve · leakage clean.

@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying odal-node-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 7859a03
Status: ✅  Deploy successful!
Preview URL: https://ff673b2e.odal-node-docs.pages.dev
Branch Preview URL: https://docs-readme-workflow.odal-node-docs.pages.dev

View logs

@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying odal-node-landing with  Cloudflare Pages  Cloudflare Pages

Latest commit: 7859a03
Status: ✅  Deploy successful!
Preview URL: https://4ef22823.odal-node-landing.pages.dev
Branch Preview URL: https://docs-readme-workflow.odal-node-landing.pages.dev

View logs

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