docs: tell contributors which four scripts they need - #36
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There are ~55 root scripts and CONTRIBUTING.md named four of them, so a newcomer opening package.json had no way to tell contributor commands from CI-only gates and release machinery they should never run locally. Add scripts/README.md: the four-command path, what verify:ci actually runs and how to re-run only the node that failed, what each name prefix owns, and the handful of scripts that behave surprisingly. It is a guide, not an inventory — package.json remains the list.
chh-ay
force-pushed
the
docs/contributor-script-guide
branch
from
July 26, 2026 10:41
a68f170 to
d46f169
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
package.jsonhas ~55 root scripts.CONTRIBUTING.mdnamed four of them, so someone opening the manifest had no way to tell contributor commands from CI-only gates and release machinery they should never run locally. The naming taxonomy is disciplined, but nothing explained it.Change
Add
scripts/README.md, covering:verify:ciruns and what it does not: CI additionally runs the full browser matrix, coverage, and the production docs buildbench/README.md, not a required CI job::workspace-node::<id>to the exact command withworkspace-tooling.ts verify-ci --dry-run; ids are not always script namesCONTRIBUTING.mdgains one paragraph pointing at the guide.Deliberately not an inventory
An earlier draft listed all root scripts and asserted with a test that every manifest entry appeared in the documentation. That was overfit: a CI-only script should not force a contributor-facing docs change, and literal markdown-content assertions fail on harmless rewording while passing when the guide is useless.
The guide is curated around workflows instead.
package.jsonremains the complete inventory.Verification
bun run lint— no errors; one pre-existing warning for the 2 MiB conformance corpusbun scripts/workspace-tooling.ts verify-ci --dry-run— prints the documented id-to-command mappingDocumentation only; no shipped code or configuration changes.