diff --git a/AGENTS.md b/AGENTS.md index abe4720fcdc52a..8a052ad23a5a17 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,6 +33,7 @@ Read only what your task needs, when it needs it: - **Contributor docs**: before starting a task, check `docs/contributors/code/` for the guide covering that kind of work (coding guidelines, backward compatibility, workspaces, releases) and read the relevant one. - **Task procedures (skills)**: before starting a matching task, read the relevant `skills//SKILL.md` (e.g. `skills/testing/SKILL.md` for writing, running, or debugging tests). +- **Release knowledge reviews**: when analyzing a named Gutenberg release to propose documentation or instruction updates, read `skills/gutenberg-release-knowledge/SKILL.md`. - **Directory guides**: some directories carry their own `AGENTS.md` and `README.md` with rules for working there (e.g. `packages/components/AGENTS.md`) — read it before changing files in that directory. ## Code quality diff --git a/skills/gutenberg-release-knowledge/SKILL.md b/skills/gutenberg-release-knowledge/SKILL.md new file mode 100644 index 00000000000000..b1409bb4d728a3 --- /dev/null +++ b/skills/gutenberg-release-knowledge/SKILL.md @@ -0,0 +1,28 @@ +--- +name: gutenberg-release-knowledge +description: Use when analyzing the pull requests and discussions shipped in a named stable Gutenberg release to identify durable guidance and prepare a focused documentation or instruction pull request. +--- + +# Gutenberg Release Knowledge + +Turn one named stable Gutenberg release into a traceable, human-reviewed documentation proposal. Run locally; do not add release scheduling or publication automation unless the user explicitly asks for it. + +## Confirm the scope + +- Require an explicit stable Gutenberg release number such as `23.6`; reject release candidates and other prereleases. +- Ask where the proposed pull request should live if the repository, base branch, or fork is not specified. +- Treat “no useful durable guidance found” as a valid result. +- Preserve existing user changes and limit repository or fork maintenance to the scope the user authorizes. + +## Follow the release-learning procedure + +1. Read [references/release-set.md](references/release-set.md) and establish the exact shipped pull-request set. +2. Shortlist discussions that may contain reusable architectural, API, compatibility, data-contract, or styling guidance. +3. Read [references/evidence.md](references/evidence.md) before retrieving and interpreting the shortlisted discussions. +4. Verify each proposed conclusion against the current implementation and canonical documentation. +5. Choose the canonical documentation or instruction destination. Do not force an instruction-file change when the evidence does not justify one. +6. Read [references/pull-request.md](references/pull-request.md) before editing files or opening the proposal. + +## Report the result + +Summarize the selected guidance, unresolved disagreement, omitted candidates, changed destinations, and validation results. When no `AGENTS.md` or Copilot instruction change was made, explain why. diff --git a/skills/gutenberg-release-knowledge/references/evidence.md b/skills/gutenberg-release-knowledge/references/evidence.md new file mode 100644 index 00000000000000..9c76264fa08b6c --- /dev/null +++ b/skills/gutenberg-release-knowledge/references/evidence.md @@ -0,0 +1,41 @@ +# Collect and interpret evidence + +Keep collection deterministic and analysis interpretive. Focus the investigation on finding important documentation gaps. + +## Collect the discussion and implementation + +For every shortlisted pull request, read: + +- the description and linked design context; +- any issue explicitly linked from a pull request that remains a documentation candidate, including the relevant discussion and resolution; +- issue comments and review summaries; +- inline review threads, including resolved threads; +- changed files and the final merged implementation; +- follow-up, revert, and compatibility work when relevant. + +## Decide what matters + +- Prioritize gaps affecting public APIs, backwards compatibility, recurring implementation mistakes, or behavior users and contributors need to understand. +- Verify a candidate against the merged implementation, current documentation, and obvious follow-up work. If its validity remains ambiguous, record the uncertainty and move on rather than expanding the investigation. +- Treat contributor roles as context about project direction, not proof that a claim is correct or agreed upon. +- Do not infer consensus from authority, comment volume, reactions, or a merge alone. Preserve meaningful disagreement and distinguish what shipped from what remains undecided. +- Treat bot output as automation, not evidence of project intent unless it links to a human-authored decision. +- Before proposing a change, confirm the guidance is Gutenberg-specific, not already covered by canonical documentation, and can be explained with enough context to be useful. If a finding depends on a broader concept, propose the canonical documentation needed to explain that concept rather than adding an isolated instruction. If that broader change is outside the scope of the release review, report the gap and omit the pull request. + +## Verify against the repository + +Before proposing text: + +1. Check the current implementation, tests, schemas, package READMEs, contributor docs, and existing instructions. +2. Confirm the proposed guidance is still true on the pull request base branch, not merely true in the release tag. +3. Look for later changes that narrow, revert, or supersede the release decision. +4. Prefer updating the canonical existing page over creating a parallel explanation. +5. Link claims to primary evidence. + +## Choose the destination + +- Update user or contributor documentation for behavior, migration, compatibility, and supported API guidance. +- Update `AGENTS.md` only for a durable engineering constraint that future feature or bug-fix work should consistently apply. +- Put a package-specific durable constraint in the affected package's nearest `AGENTS.md`. If that package has no instruction file and the evidence requires package-scoped guidance, create `packages//AGENTS.md` with only the focused guidance instead of promoting it to the repository root. +- Update `.github/copilot-instructions.md` only when the same durable constraint is useful to repository-wide coding assistance. +- Do not add instruction-file text for a release status, a single implementation choice, unresolved design preference, or guidance already expressed adequately in canonical docs. diff --git a/skills/gutenberg-release-knowledge/references/pull-request.md b/skills/gutenberg-release-knowledge/references/pull-request.md new file mode 100644 index 00000000000000..0a51fd9c6533ad --- /dev/null +++ b/skills/gutenberg-release-knowledge/references/pull-request.md @@ -0,0 +1,42 @@ +# Prepare the pull request + +Keep the output proportionate to the release. Prefer a small number of coherent pull requests. Combine related findings, and create an additional pull request only when another important documentation gap is independently reviewable and would make an existing pull request unfocused. Do not create pull requests for marginal findings merely to cover everything. + +Before editing handbook documentation or a package README, read [the documentation contribution guide](../../../docs/contributors/documentation/README.md) and follow its Markdown, heading, link, code-fence, and callout conventions. Also inspect the destination file and any closer instructions for local patterns. + +Match the destination file's existing source formatting. Do not hard-wrap new prose at an arbitrary column or reflow unchanged prose. Inspect the final diff for avoidable mid-sentence line breaks. + +## Describe the proposal + +Use a concise pull request description: + +```markdown +## What? + + + +## Why? + + + +## Discussion + +This is a release-learning proposal, not a settled conclusion. Please challenge the evidence, scope, wording, or destination. Closing this PR is a useful outcome if the guidance is not durable or correct. Discussion here will be used to improve this skill. +``` + +Include direct evidence links without turning the pull request body into the full analysis report. Open the pull request ready for review, never merge it, and keep it in the user-specified fork when requested. + +## Add labels and reviewers + +1. Query the target repository's current labels. Select the smallest set of existing labels that describes the proposed change, using labels from the source pull requests as evidence when they still fit. Never create a label just for the generated pull request. +2. Tag the people whose substantive discussion, review, or authored rationale directly informed the proposal alongside the corresponding evidence links in the pull request body. +3. Request reviews only from those named evidence participants. Exclude bots, reaction-only participants, passive requested reviewers, broad props lists, and people whose comments did not inform the proposal. When several people support the same point, keep the list focused on those whose rationale most directly informed the proposal. +4. Apply the selected labels and request the evidence-linked reviewers after opening the pull request. +5. Verify the labels and review requests. If repository permissions or collaborator rules prevent either action, keep the relevant people tagged in the pull request body and report the intended labels or reviewers with the exact limitation. + +## Validate + +- Run `npm run format -- ` and `npm run lint:md:docs -- ` for documentation changes, then inspect the resulting diff and reject unrelated reflow. Do not format untouched files. +- Run other formatting or lint checks scoped to changed files when applicable. +- Distinguish new failures from pre-existing warnings. +- Confirm the pushed branch and ready-for-review status. diff --git a/skills/gutenberg-release-knowledge/references/release-set.md b/skills/gutenberg-release-knowledge/references/release-set.md new file mode 100644 index 00000000000000..56ebd460276594 --- /dev/null +++ b/skills/gutenberg-release-knowledge/references/release-set.md @@ -0,0 +1,26 @@ +# Establish the release set + +## Resolve the shipped changes + +1. Resolve the exact stable tag `v` and the preceding stable Gutenberg tag. When the input omits a patch number, use `v.0`. +2. Extract commits and pull request numbers from the tag range. +3. Cross-check the set against the release milestone and published changelog. +4. Account for backports, release-branch-only commits, and pull requests represented by more than one commit. +5. Keep the release tag and the current default branch distinct. A shipped change may be absent, reverted, or superseded on the current branch. + +For each candidate, retain the pull request number, title, author, merge outcome, shipped commit, changed files, relevant discussion links, and release evidence. + +## Select candidates + +Prioritize discussions that may yield reusable guidance about: + +- package and editor-layer boundaries; +- public, private, or compatibility APIs; +- block parsing, serialization, and data contracts; +- styles and `theme.json` behavior; +- backward compatibility and version-specific code; +- recurring implementation or review principles. + +Deprioritize routine fixes, copy changes, generated updates, dependency bumps, and one-off implementation details unless their discussion reveals a broader rule. + +Use titles, changed paths, labels, authors, and diffs to shortlist candidates before retrieving full conversations. Do not infer architectural guidance from titles alone.