diff --git a/skills/docgen-fixup/SKILL.md b/skills/docgen-fixup/SKILL.md new file mode 100644 index 00000000..d4c5541f --- /dev/null +++ b/skills/docgen-fixup/SKILL.md @@ -0,0 +1,118 @@ +--- +name: docgen-fixup +description: Review an auto-generated OZ API docs PR (from any of the three `.github/workflows/generate-api-docs-*.yml` receivers — contracts, community-contracts, confidential-contracts) and fix the known regression patterns the docgen pipeline introduces on each run. Trigger when the user says "review PR ", "check the v5.x docs regen", "fix the regressions on the latest bot PR", or "run docgen-fixup". Scans the diff for cross-ref leaks, broken code blocks, dangling struct anchors, mangled admonitions, wrong URL rewrites, missing docs-side props, and other patterns cataloged in `references/patterns.md`, then applies direct MDX patches. Also flags NatSpec / `.adoc` mistakes that should be fixed upstream in the source contracts repo. +allowed-tools: Read, Write, Edit, Glob, Grep, Bash +inputs: + pr_number: + type: text + prompt: "Docs PR number to fix (e.g. 206)." + required: true + contracts_repo_path: + type: text + prompt: "Absolute path to the source contracts repo. Leave blank to auto-detect from the PR body's source-repo hint (matches a sibling `solidity/`, `openzeppelin-community-contracts/`, `community/`, or `openzeppelin-confidential-contracts/`)." + required: false + contracts_tag: + type: text + prompt: "Source tag / branch the PR was generated from (e.g. v5.7.0-rc.0, master). Leave blank to parse from the PR body." + required: false + mode: + type: choice + prompt: "Run mode. interactive = show findings, wait for approval per pattern. automatic = apply every fix from `references/patterns.md` and report." + options: + - interactive + - automatic + default: interactive + required: false +--- + +# docgen-fixup + +Fix the known regression patterns in an auto-generated API docs PR before it merges. The docs bot runs three receivers — one per source repo — each on a release tag / master commit, and opens a PR against `content//**/*.mdx`: + +| Workflow | Source repo | Docs slice | Versioned | +|-----------------------------------------------------|---------------------------------------------------|--------------------------------|-----------| +| `.github/workflows/generate-api-docs-contracts.yml` | `OpenZeppelin/openzeppelin-contracts` | `content/contracts/.x/` | yes | +| `.github/workflows/generate-api-docs-community-contracts.yml` | `OpenZeppelin/openzeppelin-community-contracts` | `content/community-contracts/` | no | +| `.github/workflows/generate-api-docs-confidential-contracts.yml` | `OpenZeppelin/openzeppelin-confidential-contracts` | `content/confidential-contracts/` | no | + +All three run the same transformer (`docgen/templates-md/` + `scripts/convert-adoc.js` + `scripts/process-mdx.js`), so the same regression patterns apply to all three. The transformer is intentionally kept simple — it does not paper over upstream NatSpec / `.adoc` mistakes, and it does not try to be exhaustive about every edge case. Those get caught here. + +## When to use + +- The docs bot just opened a PR (title starts with `[CI] Update API docs for OpenZeppelin/…`). +- The user names a PR number and asks for a review / fix pass. +- Before merging any auto-generated docs update. + +Do **not** use this skill for: + +- Hand-written guide pages that were not touched by the bot (use a normal edit). +- Changes to `docgen/templates-md/` or `scripts/convert-adoc.js` — those are transformer changes, not fixup. Keep the transformer minimal; catalog new regression patterns here instead. + +## Guiding principle + +The docgen transformer stays minimal. It fixes only genuine regex / template bugs — not upstream authoring mistakes. Everything the docgen leaves broken should either be: + +1. **Fixed upstream** in the source `.sol` NatSpec or `docs/modules/ROOT/pages/*.adoc`, so the next regen produces correct output — and cataloged in `references/patterns.md` for the next reviewer. +2. **Patched directly** in the generated MDX for the current PR, so the PR is correct without waiting for a regen. + +Both. Upstream fixes drop the pattern from future PRs; direct patches unblock the current one. + +Some patterns have **no clean upstream fix** because the value depends on a docs-side decision (e.g. which Wizard `version=` to pin for a given release). Those are `n/a` for upstream and are re-applied on every regen. That is not a bug — it is the boundary between what upstream owns and what the docs repo owns. + +## Inputs + +| Input | Required | Notes | +|-----------------------|----------|--------------------------------------------------------------------| +| `pr_number` | yes | PR to review (auto-generated by the bot) | +| `contracts_repo_path` | no | absolute path; auto-detected from the PR body if omitted | +| `contracts_tag` | no | git tag / ref; parsed from the PR body if omitted | +| `mode` | no | `interactive` (default) or `automatic` | + +Never invent an SHA, a path, or a PR number. If auto-detection fails, stop and report which field is missing. + +## Workflow + +Follow `process.md` end-to-end. It: + +1. Validates inputs and resolves the source repo + tag from the PR body. +2. Fetches the PR diff and lays out per-file patches under `/tmp/pr--diffs/`. +3. Runs the pattern catalog in `references/patterns.md` against each changed file. +4. Emits a findings block per pattern (interactive mode waits for approval; automatic mode applies immediately). +5. Applies direct MDX patches, opens upstream PRs where warranted, and updates the PR branch. + +## Pattern catalog + +`references/patterns.md` is the source of truth for what this skill knows how to fix. Each entry has: + +- **Symptom** — what the reader sees in the generated MDX. +- **Detection** — the grep / heuristic that finds it. +- **Root cause** — where in the pipeline (docgen resolver / regex / template / upstream NatSpec / upstream `.adoc`) the pattern comes from. +- **Upstream fix** — the change to the source `.sol` / `.adoc` so the next regen produces correct output. Skip if there is no clean upstream fix. +- **MDX patch** — the direct patch to apply on the current PR. +- **Example** — a concrete case from a prior regen. + +When you discover a **new** regression pattern that isn't in the catalog, append it to `references/patterns.md` in the same shape as an existing entry, and note it in the run report. The catalog is a living document — every reviewer contributes. + +## Scope of edits + +Edit only: + +- Files inside the resolved PR's diff — do not touch pages the bot did not modify. +- Upstream source files under `/contracts/**/*.sol` or `/docs/modules/ROOT/pages/**/*.adoc` when a pattern has an upstream fix — via a **separate branch and PR** on the contracts repo, never in a direct commit to `master`. + +Do **not**: + +- Modify `docgen/templates-md/` or `scripts/convert-adoc.js`. If a pattern seems to demand a transformer change, stop and surface it to the user — that is a separate design decision, not a fixup. +- Touch docs slices the current PR is not scoped to. Each of the three docgen workflows targets a single slice (`content/contracts/.x/`, `content/community-contracts/`, or `content/confidential-contracts/`); patch only inside that slice. +- Rewrite prose beyond what a specific pattern requires. + +## End of run + +Produce a compact report per `references/report-template.md`: + +- Files fixed, per pattern, with line hints. +- Upstream PRs opened (URL + one-line summary each). +- Any new patterns added to `references/patterns.md`. +- Anything skipped (with the reason). + +Do not write the report to a file unless the user asks — inline in the final message is enough. diff --git a/skills/docgen-fixup/process.md b/skills/docgen-fixup/process.md new file mode 100644 index 00000000..f324f283 --- /dev/null +++ b/skills/docgen-fixup/process.md @@ -0,0 +1,172 @@ +# docgen-fixup process + +Deterministic workflow. Steps run in order. If a step fails, stop and surface — do not skip ahead. + +All paths in this document are relative to the docs repo unless prefixed ``. + +--- + +## Step 0 — Validate inputs + +Inputs arrive from the frontmatter `inputs` schema. Validate inline: + +- `pr_number`: is a positive integer; PR exists and is open on `OpenZeppelin/docs`. +- `contracts_repo_path` (if provided): exists and is a git repo. +- `contracts_tag` (if provided): resolves in the source contracts repo. + +Missing / invalid input is a hard error — return an error message naming every failing field. Never invent values. + +## Step 1 — Fetch PR metadata + +``` +gh pr view --repo OpenZeppelin/docs \ + --json title,body,headRefName,baseRefName,changedFiles,url,mergeable +``` + +Record `headRefName` (branch), `baseRefName` (target — usually `main`), and the body. + +## Step 2 — Resolve source repo, docs slice, and tag + +Parse the PR body: + +- **Repository** line names the source repo (e.g. `OpenZeppelin/openzeppelin-contracts`, `OpenZeppelin/openzeppelin-community-contracts`, `OpenZeppelin/openzeppelin-confidential-contracts`). +- **Reference** line names the tag / branch (e.g. `v5.7.0-rc.0`, `master`). +- **Output Directory** line names the docs slice (e.g. `content/contracts/5.x/api`, `content/community-contracts/api`, `content/confidential-contracts/api`). + +Fill in `contracts_repo_path` and `contracts_tag` from inputs if provided; otherwise from the body. Then: + +- Auto-detect the local checkout. Walk the parent of `` and any known sibling roots. For each candidate directory, run `git -C remote get-url origin 2>/dev/null` and match against the parsed source repo. Common names to try, per source repo: + + | Source repo | Candidate dir names | + |--------------------------------------------------------|--------------------------------------------------------| + | `OpenZeppelin/openzeppelin-contracts` | `solidity`, `openzeppelin-contracts` | + | `OpenZeppelin/openzeppelin-community-contracts` | `community`, `openzeppelin-community-contracts` | + | `OpenZeppelin/openzeppelin-confidential-contracts` | `confidential`, `openzeppelin-confidential-contracts` | + + Fall back to a `git remote -v | grep ` sweep across all directories under the workspace root if none of the common names hit. Do not invent a path. + +- Fetch the tag: `git -C fetch origin refs/tags/:refs/tags/` for a tag, or `git -C fetch origin ` for a branch (community-contracts and confidential-contracts often generate against `master`). +- Create a read-only worktree pinned at the ref: + ``` + git -C worktree add /tmp/oz-src- + ``` + Use a slug that includes both the repo short-name and the ref so parallel runs don't collide: `oz-src-contracts-v5.7.0-rc.0`, `oz-src-community-master`, etc. Remove in Step 11. + +Note the docs slice from the PR body so pattern-scan globs stay scoped to that slice (`content//**/*.mdx`) and don't false-positive on other slices. + +If auto-detection or fetching fails, stop with a clear error naming both the parsed repo and the candidate paths that were tried. + +## Step 3 — Check out the PR branch locally + +``` +git -C fetch origin pull//head:pr- +git -C checkout pr- +``` + +Record the previous branch so it can be restored at end of run. + +## Step 4 — Capture per-file diffs + +Stage the diff for pattern scanning: + +``` +mkdir -p /tmp/pr--diffs +for f in $(gh pr diff --repo OpenZeppelin/docs --name-only); do + safe=$(echo "$f" | sed 's|/|__|g') + git -C diff origin/ pr- -- "$f" > "/tmp/pr--diffs/$safe.diff" +done +``` + +## Step 5 — Run the pattern catalog + +For each pattern in `references/patterns.md`, in order: + +1. Run its **Detection** command / heuristic against the diff (or the PR branch's MDX, whichever the pattern specifies). +2. Collect hits — one row per (file, line, matched snippet). +3. For each hit, verify against upstream source in `/tmp/oz-src-/` before flagging. Skip if the hit is a false positive (the pattern description says how). +4. If the pattern **has** an upstream fix, note the upstream file + line for the eventual upstream PR. + +## Step 6 — Findings gate (interactive mode) + +Emit ONE findings block per pattern that has hits. Format: + +``` +## Pattern: +Symptom: +Root cause: + +### Hits +- : — + → MDX patch: + → Upstream: : — (or: "no clean upstream fix") + +### Approval +Reply "apply" to patch the MDX + open the upstream PR, "skip" to leave this pattern alone this run, or refine to change the plan. +``` + +End the turn after emitting all findings blocks. Wait for the user's response. Accept: `apply`, `apply all`, `skip`, or refinements. Anything else re-emit + wait. + +In `automatic` mode, skip this gate — apply every patch immediately. + +## Step 7 — Apply MDX patches + +For each approved pattern: + +1. Read the affected MDX file (must Read before Edit). +2. Apply the direct patch described in `references/patterns.md`. Use `Edit` with enough surrounding context to make the `old_string` unique. +3. Verify the patch: re-grep for the pattern's detection signature on the file; the hit should be gone. + +Never batch a rewrite. One `Edit` per (file, hit). + +## Step 8 — Open upstream PRs + +For each approved pattern with an upstream fix: + +1. Group hits by target file — one branch per file is fine, one branch per pattern is better. +2. Create a worktree on the source contracts repo (do not disturb the user's current checkout): + ``` + git -C worktree add /tmp/oz-upstream- origin/master + ``` +3. Apply the upstream edits in that worktree. +4. Commit with a subject in the form `docs: in `. +5. Push to the user's fork: + ``` + git -C /tmp/oz-upstream- push + ``` + The fork remote is the one whose URL points at the user's GitHub username. Do not push to `origin` on the contracts repo. +6. Open a PR: + ``` + gh pr create --repo --base master --head : \ + --title "" --body "" + ``` +7. Remove the worktree. + +Record the PR URL for the final report. + +## Step 9 — Commit and push the MDX patches + +``` +git -C add +git -C commit -m "fixup: apply docgen-fixup patterns to " +git -C push origin pr-: +``` + +Only push if the user's docs remote points at their fork or they have write access to `OpenZeppelin/docs`. Verify with `git remote -v` before pushing. If neither is true, stop and surface — do not force it. + +## Step 10 — Catalog new patterns (if any) + +If Step 5 surfaced a regression pattern that is NOT in `references/patterns.md`: + +1. Draft a new entry in the same shape as an existing one (Symptom / Detection / Root cause / Upstream fix / MDX patch / Example). +2. Append it to `references/patterns.md`. +3. Commit under the same message so the catalog grows with each run. + +## Step 11 — Restore local state + +- Return the docs repo to the branch it was on when the run started. +- Remove `/tmp/oz-src-/`, `/tmp/oz-upstream-/`, `/tmp/pr--diffs/`. +- Do not delete the `pr-` local branch — leave it available for follow-up. + +## Step 12 — Report + +Emit the report per `references/report-template.md`. Inline in the final message — do not write to a file unless the user asks. diff --git a/skills/docgen-fixup/references/patterns.md b/skills/docgen-fixup/references/patterns.md new file mode 100644 index 00000000..0bff46a6 --- /dev/null +++ b/skills/docgen-fixup/references/patterns.md @@ -0,0 +1,187 @@ +# Regression pattern catalog + +Every pattern the `docgen-fixup` skill knows how to detect and fix. Add new entries as new regressions emerge; do not delete entries even when the underlying pipeline bug is fixed — pinned regens against old tags can still hit them. + +All patterns apply to any of the three source-repo receivers unless the entry says otherwise: `contracts` (versioned, `content/contracts/.x/`), `community-contracts` (unversioned, `content/community-contracts/`), `confidential-contracts` (unversioned, `content/confidential-contracts/`). + +Each entry: + +- **Symptom** — what the reader sees in the generated MDX. +- **Detection** — a grep or scan that finds hits. Scope globs to the docs slice from the PR body — see Step 2 of `process.md`. +- **Root cause** — where in the pipeline (docgen resolver, regex, template, `downdoc`, upstream NatSpec, upstream `.adoc`, docs-side decision) it comes from. +- **Upstream fix** — the change to the source `.sol` / `.adoc` so the next regen produces correct output. `n/a` if there is no clean upstream fix (e.g. the value depends on a docs-side decision, or the pattern is a transformer bug fixable only in the docs repo). +- **MDX patch** — the direct patch to apply on the current PR. +- **Example** — one concrete case from a prior regen. + +--- + +## 1. Broken Solidity code block in a hand-authored guide + +**Symptom**: a fenced ```` ```solidity ```` block inside a guide `.mdx` has mangled indentation on interior lines and/or a missing closing brace. Copy-pasting the block would not compile. + +**Detection**: +``` +git diff origin/ pr- -- 'content/**/*.mdx' \ + | awk '/```solidity/,/```/' \ + | grep -nE '^\+' \ + | grep -E '^\+ {0,4}(super|return|revert|emit)|^\+\}$' +``` +False-positive check: the same block on `origin/` did NOT have the same shape (the regression is new in this PR). + +**Root cause**: `downdoc` mangles the contents of triple-backtick fenced blocks when they live inside a `.adoc` source (it treats them as prose, strips `//` comment lines, de-indents nested `{}`). `scripts/convert-adoc.js` preprocesses these to `[source,lang]\n----\n...\n----` form before running `downdoc` — but if a maintainer bypasses that preprocess (or a new fenced-block variant slips through the regex), the mangle returns. + +**Upstream fix**: rewrite the block in the source `.adoc` as `[source,lang]\n----\n...\n----` explicitly, or as `include::api:example$path/to/File.sol[]`. Do not rely on the preprocess to catch new syntaxes. + +**MDX patch**: restore indentation and closing braces by copying the corresponding code from the source `.adoc` (or the referenced example `.sol`). + +**Example** (PR #206): `content/contracts/5.x/extending-contracts.mdx:52-56` — `super.revokeRole(...)` dedented to 4 spaces, function closing `}` at column 0, function-level closing `}` missing. + +--- + +## 2. NatSpec `{Type}` / `{Contract.method}` leaks as raw anchor fragment + +**Symptom**: prose inside an API MDX contains a bare `#Contract-something-Type` fragment sitting in the middle of a sentence (not inside a Markdown link). + +**Detection**: +``` +grep -rnP '(?` anywhere in the file. Clicking navigates to a non-existent fragment. + +**Detection**: +``` +python3 -c ' +import re, glob +for f in glob.glob("content/**/api/**/*.mdx", recursive=True): + t = open(f).read() + defs = set(re.findall(r"` — inheritance-related dangles are a separate, broader issue. + +**Root cause**: `contract.hbs` emits `` for structs (as of the fix that shipped with PR #206). For **enums** and **user-defined value types** it does not — those are still on the "if a NatSpec ref hits one, the link dangles" path. Slugs for those AST node types are still registered by `getAllLinks`, so `{EnumType}` in NatSpec produces a link to a nonexistent anchor. + +**Upstream fix**: rewrite the NatSpec ref to inline code (`` `EnumType` ``) or link to the contract page (`{Contract}`). + +**MDX patch**: either emit the missing `` alongside the contract's main anchor, or rewrite the link into inline code. Prefer the anchor when the reader benefits from a jump target. + +**Example** (PR #206): `content/contracts/5.x/api/utils.mdx` — `[RateLimiter.RefillingBucket](#RateLimiter-RefillingBucket)` and `[RateLimiter.SlidingWindow](#RateLimiter-SlidingWindow)` in the RateLimiter description. Fixed by rendering full struct sections (see the `contract.hbs` change that shipped with PR #206). + +--- + +## 5. AsciiDoc heading conversion leaves trailing `===` + +**Symptom**: an MDX heading like `### Section title ===` — the trailing equals signs from an AsciiDoc symmetric setext form leaked through into the Markdown output. + +**Detection**: +``` +grep -rnE '^#+ .*=+ *$' content/**/*.mdx +``` + +**Root cause**: NatSpec author wrote `=== Section title ===` (equals on both sides — legacy AsciiDoc symmetric setext). `docgen/templates-md/helpers.js processCallouts()` converts leading `===` to `###` but does not strip the trailing `===`. The transformer regex is deliberately kept narrow — this is an upstream authoring mistake. + +**Upstream fix**: drop the trailing `===` in the source `.sol` NatSpec. Standard form in this codebase is leading-only (`* === Section title`). + +**MDX patch**: strip the trailing `===` from the heading. + +**Example** (PR #206): `content/contracts/5.x/api/utils.mdx:9286` — `### Limiter vs. entries ===` from `contracts/utils/RateLimiter.sol:23`. Upstream fixed in [OpenZeppelin/openzeppelin-contracts#6612](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/6612). + +--- + +## 6. `[TIP]==== ... ====` block admonition dumped as prose + +**Symptom**: content that should be wrapped in a `` component renders as plain paragraph text, often with two or three empty lines where the block delimiters used to be. + +**Detection**: +``` +# Blank runs of 3+ lines in generated MDX are often a signature of stripped admonition delimiters +grep -rnE '^$' content/**/*.mdx | awk -F: '{print $1":"$2}' | uniq -c | awk '$1 >= 3' +# Then verify each hit against the source .adoc to see if a [TIP]====/[NOTE]==== block sat there. +``` + +**Root cause**: `downdoc` converts AsciiDoc `[TIP]==== ... ====` block admonitions into `
💡 TIP
…
` (HTML description list, with an emoji). `scripts/convert-adoc.js` then converts this shape back to ``. If a new emoji shape appears (or `downdoc` upgrades change the wrapper), the character-class regex in `convert-adoc.js` will miss it, the final cleanup will strip the `
` tags, and the inner content survives as prose. + +**Upstream fix**: `n/a`. Keep the `.adoc` in the standard `[TIP]====` block form; when adding a new emoji or a new admonition, extend the character class in `scripts/convert-adoc.js` accordingly (that IS a legitimate transformer change, not upstream-error masking). + +**MDX patch**: wrap the orphaned prose in `` (`` for WARNING / IMPORTANT / CAUTION). + +**Example** (PR #206): `content/contracts/5.x/paymasters.mdx:333-342` — a `[TIP]====` block in `paymasters.adoc:325-332` dumped as prose because `convert-adoc.js` was missing 💡 in its emoji character class. Transformer fix landed with PR #206; the block itself was patched into a `` in the same PR. + +--- + +## 7. External `docs.openzeppelin.com` URL rewritten to a broken internal path + +**Symptom**: a link on an OZ docs page points at `/defender/module/actions#some-anchor` (or another internal path with a fragment), but the fragment does not exist on the target page. Clicking navigates to the page but not the intended section. + +**Detection**: +``` +# Extract internal links with fragments, verify each anchor exists on the target page +grep -rnoE '\]\(/[a-z0-9/-]+#[a-z0-9-]+\)' content/**/*.mdx +``` +For each match, resolve `/` → `content/.mdx` and grep the file for ``. + +**Root cause**: as part of consolidating docs onto one site, the transformer rewrites absolute `https://docs.openzeppelin.com/…` URLs to relative site paths. The rewrite is purely textual — it does not verify the target anchor exists. When the historical site's anchor scheme differed from the current MDX site's (or when the referenced content actually lives on a different page now), the result is a broken in-site link. + +**Upstream fix**: rewrite the xref in the source `.adoc` to point at the correct target page and (optionally) anchor. Use `xref:defender::module/foo.adoc[Label]` — no fragment — if the whole page is the target. + +**MDX patch**: repoint the link to the correct target page. Drop the fragment if the whole page is the target. + +**Example** (PR #206): `content/contracts/5.x/governance.mdx:39` and `:114` — both `Defender Proposals` links pointed at `/defender/module/actions#transaction-proposals-reference` (anchor did not exist). Correct target: `/defender/module/transaction-proposals`. Upstream fixed in [OpenZeppelin/openzeppelin-contracts#6612](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/6612). + +--- + +## 8. `` rendered without a `version=` prop + +**Symptom**: an `` component in the generated MDX has no `version="…"` attribute. Renders the Wizard against an unpinned default that may not match the release the docs page targets. + +**Detection**: +``` +grep -rnE '' content/**/*.mdx \ + | grep -v 'version=' +``` +Applies to every slice that references the Wizard component (currently `content/contracts/.x/*.mdx`, `content/contracts-cairo/*/wizard.mdx`, `content/stellar-contracts/get-started.mdx`). + +**Root cause**: The source `.adoc` uses the legacy `` HTML custom element (`` or ``). `scripts/convert-adoc.js` translates the tag to the `` React component and maps `data-tab` → `tab`, `data-lang` → `lang`, but it cannot infer a `version=` — the version is a **docs-side decision**, chosen per release by the docs maintainers, not encoded in the source `.adoc`. + +**Upstream fix**: `n/a`. The `.adoc` source deliberately does not carry a version. See the guiding principle in `SKILL.md`: some patterns cross the boundary between what upstream owns and what the docs repo owns. + +**MDX patch**: add `version=".."` to every `` occurrence in the slice. Match the release the PR targets — for `contracts`, use the tag from the PR body's **Reference** line, dropping the leading `v` and any `-rc.N` suffix. For unversioned slices (`community-contracts`, `confidential-contracts`), use the version pinned in the source repo's `package.json` at the ref being generated, unless the docs maintainers have a slice-specific convention. + +**Examples** (PR #206): +- `content/contracts/5.x/wizard.mdx:12` — `` → `` ([review comment](https://github.com/OpenZeppelin/docs/pull/206#discussion_r3589847696)) +- `content/contracts/5.x/accounts.mdx:13` — `` → `` ([review comment](https://github.com/OpenZeppelin/docs/pull/206#discussion_r3590455407)) diff --git a/skills/docgen-fixup/references/report-template.md b/skills/docgen-fixup/references/report-template.md new file mode 100644 index 00000000..363aab58 --- /dev/null +++ b/skills/docgen-fixup/references/report-template.md @@ -0,0 +1,52 @@ +# docgen-fixup run report + +Emit inline at end of run. Do not write to a file unless the user asks. + +## PR reviewed + +- PR: [OpenZeppelin/docs#]() +- Source: `@` +- Base: `` +- Head: `` +- Changed files: + +## Patterns matched + +For each pattern from `references/patterns.md` that had hits: + +### + +- Hits: +- MDX patched: +- Upstream PR: +- Skipped: + +Example line for a hit: + +- `:` — + +## Upstream PRs opened + +- [#]() — + +## New patterns discovered + +For any regression pattern encountered that was not in the catalog: + +- Name: `` +- File added: `references/patterns.md` (new entry appended) +- One-line description +- First observed on: PR # + +If none: `None.` + +## Skipped / needs human review + +- : — + +If none: `None.` + +## Next steps + +- What the user should verify before merging (e.g. render one of the patched pages in the dev server). +- Any pattern that has no clean fix yet.