docs: fix typos, grammar, and broken code snippets in contributor docs#7298
Open
andromia3 wants to merge 1 commit intoShopify:mainfrom
Open
docs: fix typos, grammar, and broken code snippets in contributor docs#7298andromia3 wants to merge 1 commit intoShopify:mainfrom
andromia3 wants to merge 1 commit intoShopify:mainfrom
Conversation
None of these change behaviour — they're all inside docs/cli/*.md
contributor-facing markdown. Each fix was verified against the
surrounding prose or against runnable code.
Broken code snippets (would fail if a contributor copy-pasted them):
- troubleshooting.md: `const import {functionA} from 'my-module'` was
invalid syntax — a `const` before `import` doesn't parse. Dropped
the `const`.
- testing-strategy.md: the example test did `const got = await load()`
and then asserted on `app.name`, but `app` isn't defined in that
scope. Changed to `got.name`, which is what the previous line bound.
Install instructions that don't satisfy the repo's engines:
- cross-os-compatibility.md: the Linux contributor setup installs
Node 18 via `setup_18.x`, but `packages/cli/package.json` declares
`"engines": { "node": ">=20.10.0" }` and `.nvmrc` pins v24.1.0.
Following the old guide leaves a contributor unable to run
`pnpm install`. Bumped to `setup_24.x` to match `.nvmrc`.
Typos and missing words that affect readability:
- get-started.md: "might come handy" -> "might come in handy".
- get-started.md: "Type-checks all the packagesusing the Typescript
`tsc` tool" -> "packages using the TypeScript `tsc` tool". Missing
space plus brand capitalisation.
- conventions.md: "the name must match the name of the command
represent" was missing a word — now "the name of the command it
represents".
- conventions.md: "spins up an server" -> "spins up a server".
- conventions.md: the `browser` bullet in the public-modules list was
missing a colon; the neighbouring `node` and `common` bullets use
`- \`foo\`: For modules...`, so added the colon for consistency.
- architecture.md: "an horizontally-distributed" -> "a
horizontally-distributed" (consonant sound, no `n`).
- architecture.md: "boundaries that leads" -> "boundaries that lead"
(plural subject agreement).
- performance.md: "code that don't map 1-to-1" -> "code that doesn't
map 1-to-1" (singular subject agreement).
- performance.md: "As a **last resource**" -> "As a **last resort**"
(wrong word).
- testing-strategy.md: the Given/When/Then note said "blocks, given,
when, and using code comments" — "then" was missing from the list.
Also "the code test" -> "the test code" (word order).
- testing-strategy.md: "Github Actions" -> "GitHub Actions" in the
heading, plus "marge" -> "merge" and "Github" -> "GitHub" in the
body of that section.
- cross-os-compatibility.md: "standard library work more consistently"
-> "standard library works" (singular subject agreement).
No changeset — `docs/cli/**` isn't user-facing.
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
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.
WHY are these changes introduced?
Cleanup pass on the contributor-facing docs under `docs/cli/`. Every change is either a broken code snippet, an install instruction that doesn't satisfy `package.json#engines`, or a grammar/typo bug. All verified against the current state of the repo.
WHAT is this pull request doing?
Broken code snippets — copy-pasting these would fail:
Install instruction below the engine requirement:
Typos, missing words, and agreement bugs:
How to test your changes?
Docs-only, every change is inside a `docs/cli/*.md` file. Rendering on GitHub or in an editor previewer is enough to verify each fix.
Post-release steps
None.
Checklist