Skip to content

build(readme): sync only shared blocks so packages keep their own READMEs - #83

Closed
apresmoi wants to merge 1 commit into
mainfrom
docs/readme-partial-sync
Closed

build(readme): sync only shared blocks so packages keep their own READMEs#83
apresmoi wants to merge 1 commit into
mainfrom
docs/readme-partial-sync

Conversation

@apresmoi

@apresmoi apresmoi commented Aug 9, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • replace the wholesale root-README copy in sync-package-readmes.mjs with a partial sync: only regions wrapped in <!-- polycss:shared:<name>:start/end --> are mirrored from the root README, and everything between them is package-specific
  • mark four shared blocks in the root README — links, packages, showcase, license — and adopt them in the core, polycss, react, and vue READMEs
  • give those four packages real, hand-written READMEs: core documented the wrong package (it told readers to npm install @layoutit/polycss and showed JSX), and vue shipped React TSX examples
  • a package opts into a block simply by containing its markers, so fonts and morph need no exemption list and are left untouched
  • add pnpm check:readmes (--check) and run it in CI, so a shared block edited in the wrong place fails the build instead of drifting
  • document the contract in AGENTS.md and add a PR-checklist line

Previously prepack copied the root README over all four packages on every npm pack / npm publish, so a package-specific README could not reach npm — the file reviewed in a PR was not the file published. Now what is committed is what ships.

Validation

  • pnpm test
  • pnpm build:packages
  • pnpm check:readmes
  • npm pack --dry-run in packages/core: prepack reports 0 READMEs updated, and the tarball carries core's own 5.9 kB README rather than the 9.9 kB root copy
  • drift check verified by hand: mutating a shared block in a package README fails --check with a non-zero exit, and passes again once restored

@apresmoi apresmoi closed this Aug 9, 2026
@apresmoi
apresmoi deleted the docs/readme-partial-sync branch August 9, 2026 15:19
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