Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ pnpm dev # local preview
pnpm build:local # build + frontmatter validation (CI runs this too)
pnpm lint:slugcheck # permalink rules
pnpm lint:changelog # release notes entries (see below)
pnpm lint:codeblocks # code samples parse (see below)
```

- Changed a permalink or moved a page? **Add the redirect in this PR**, in the highest-numbered file of `apps/docs/redirects/{en,pt-br}/`, and list it on the redirect row of the PR checklist.
Expand Down Expand Up @@ -82,6 +83,30 @@ On a PR that changes a changelog page, the **Changelog entries** check runs the
pages the PR changes and annotates each finding on its line. It does not block the merge: you decide
whether to fix the entry there.

### Code samples

Readers paste samples into the Console, a terminal, or a function, so a sample has to parse:
a `json` block is JSON, a JavaScript or TypeScript block has no syntax errors, and the JSON body of
a `curl --data` is JSON. `pnpm lint:codeblocks <files>` checks the pages you pass it, and every page
when you pass none. It accepts the conventions the docs use on purpose:

- in a `json` block or a `curl` body, a bare `<placeholder>` where a value goes, such as
`"id": <your-rule-id>`. In JavaScript and TypeScript, a placeholder goes inside a string:
`'<your-token>'`;
- `...` or `…` for members, elements, or statements left out;
- a fragment: object members without their braces, or the body of a class or interface;
- `diff` in the fence meta (` ```javascript diff `), which checks the removed and the added side;
- `jsonc` for JSON that allows comments and trailing commas, and `jsonl` for one value per line.

A block that is partial on purpose, such as a function split across two steps, takes `nolint` in its
fence meta (` ```typescript nolint `). Nothing renders the meta.

A method signature alone, such as `async fetch(request, env, ctx)`, is not JavaScript. Give it an
elided body, `async fetch(request, env, ctx) { … }`, and the block parses.

On a PR, the **Code blocks** check runs the same script over the pages the PR changes and annotates
each finding on its line. It does not block the merge: you decide whether to fix the sample there.

## The PR

- Title: `type(scope): imperative summary`, enforced by CI. **No ticket codes in the title**: the branch name and the Related issue field carry those, and squash makes titles permanent history.
Expand Down
6 changes: 6 additions & 0 deletions .github/GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,12 @@ line and turns red when it finds one. It never blocks the merge: the author deci
the entry in the same PR. It runs outside the CI gate and is not a required check, and it should
stay that way.

**Code blocks** is advisory, and it is not a ratchet. It parses the code samples on the pages
a PR changes (JSON blocks, JavaScript and TypeScript syntax, and the JSON body of a `curl --data`),
annotates each finding on its line, and turns red when it finds one. It never blocks the merge: the
author decides whether to fix the sample in the same PR. It runs outside the CI gate and is not a
required check, and it should stay that way.

### Checks that ratchet

Five checks carry more debt than any one PR can clear, so they are frozen at a baseline in
Expand Down
69 changes: 69 additions & 0 deletions .github/workflows/code-blocks.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Checks the code samples on the pages a PR changes: JSON blocks parse, JavaScript and TypeScript
# blocks have no syntax errors, and the JSON body of a `curl --data` parses. See
# apps/docs/scripts/lint-codeblocks.mjs for what counts and which conventions it accepts.
#
# Advisory on purpose. A finding turns this check red and annotates the lines, but the check is not
# a required status check and must not become one: the PR author decides whether to fix it. It is a
# workflow of its own, outside the CI gate, for that reason.
name: Code blocks

on:
pull_request:
types: [opened, synchronize, reopened]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true

jobs:
code-blocks:
name: Code blocks
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0

# On a PR, only the pages it changes: a finding then belongs to what the author touched, not to
# debt the PR did not create. A PR that changes the script or this workflow, and a manual run,
# check every page.
- name: Collect changed pages
id: pages
if: github.event_name == 'pull_request'
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
# The diff goes to a file first: a failed diff must fail the step, not read as "no page
# changed". Only grep's "no match" is tolerated.
run: |
git diff --name-only --diff-filter=ACMR "$BASE_SHA...$HEAD_SHA" > changed.txt
grep -E '^apps/docs/src/(content|includes)/.*\.mdx?$' changed.txt > changed-pages.txt || true
if grep -qxE 'apps/docs/scripts/lint-codeblocks\.mjs|\.github/workflows/code-blocks\.yml' changed.txt; then
echo "count=all" >> "$GITHUB_OUTPUT"
exit 0
fi
count=$(wc -l < changed-pages.txt | tr -d ' ')
echo "count=$count" >> "$GITHUB_OUTPUT"
if [ "$count" = 0 ]; then
echo "No page changed in this PR, so there are no code blocks to check." >> "$GITHUB_STEP_SUMMARY"
fi

- uses: ./.github/actions/setup
if: github.event_name != 'pull_request' || steps.pages.outputs.count != '0'

- name: Lint the code blocks
if: github.event_name != 'pull_request' || steps.pages.outputs.count != '0'
env:
EVENT: ${{ github.event_name }}
COUNT: ${{ steps.pages.outputs.count }}
run: |
if [ "$EVENT" = pull_request ] && [ "$COUNT" != all ]; then
tr '\n' '\0' < changed-pages.txt | xargs -0 node apps/docs/scripts/lint-codeblocks.mjs
else
node apps/docs/scripts/lint-codeblocks.mjs
fi
5 changes: 5 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,10 @@ preferences.
`anchor`, one tag from a closed list, and a closing link to a page in the same language. Run
`pnpm lint:changelog`; the rules and the tag list are in
[CONTRIBUTING.md](.github/CONTRIBUTING.md#changelog-entries). Never rewrite an older entry.
- **Code samples parse.** A `json` block is JSON, a JavaScript or TypeScript block has no syntax
errors, and the body of a `curl --data` is JSON. Run `pnpm lint:codeblocks <files>` on the
pages you changed; the conventions it accepts are in
[CONTRIBUTING.md](.github/CONTRIBUTING.md#code-samples).
- Do not name competitors anywhere: not in pages, not in commit messages, not in pull request
descriptions.

Expand All @@ -62,6 +66,7 @@ pnpm lint:slugcheck # permalink rules
pnpm lint:navcheck # navigation trees
pnpm lint:links # internal links, without a build
pnpm lint:changelog # release notes entries: anchors, order, tags, closing link
pnpm lint:codeblocks # code samples parse: JSON, JS/TS, curl bodies
pnpm format # prettier
```

Expand Down
1 change: 1 addition & 0 deletions apps/docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
"lint:links": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/lint-links.ts",
"lint:navcheck": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/lint-navcheck.ts",
"lint:changelog": "node ./scripts/lint-changelog.mjs",
"lint:codeblocks": "node ./scripts/lint-codeblocks.mjs",
"nav:url-map": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/nav/url-map.ts",
"nav:migrate": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/nav/migrate-permalinks.ts",
"nav:retarget": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/nav/retarget-links.ts",
Expand Down
Loading
Loading