Uh oh!
There was an error while loading. Please reload this page.
Assign a release owner to autogen-docs PRs - #1111
Merged
Merged
Conversation
Review-then-merge-by-committee left these PRs with no clear owner: five contributors each had a review request, nobody owned merging, and PRs stalled for days while later releases queued behind them. Only 2 of 10 toolhive docs PRs since July 1 had every requested reviewer approve within the 2-business-day SLO. Two changes to fix the incentives: Name an owner. A new step resolves whoever cut the upstream release and sets them as the PR assignee as well as a reviewer. They collect the remaining approvals and merge. `release.author` is unreliable here (it returns the release App for toolhive and registry-server), so the resolution falls back to the merger of the upstream release PR, then the tagged commit's author. Stop requesting reviews nobody needs. The skill now classifies each release contributor as docs-facing or not from the diffs it already read in Phase 2, and writes REVIEWERS.json. Contributors whose work had no reader-visible surface get no review request; they are named on one cc line in the PR body and one line in the Slack message, asking them to speak up if the call was wrong. The owner is always requested regardless of classification. A missing or stub REVIEWERS.json falls back to requesting everyone, so losing the classification degrades to today's behavior rather than to silence. The Slack message is restructured around the same idea: owner and their duty first, then one short line per reviewer, then a single consolidated FYI line. The owner-duty and FYI wording is fixed in the poster script rather than composed per release so it stays consistent and short enough to actually get read. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Auditing every autogen-docs PR since July 1: 38% needed a
post-generation correction (60% for toolhive), via either a human
commit or an @claude/@copilot fix request. The interventions cluster
into four repeatable failure modes, three of which the skill can
prevent. Each addition names the release that hit it, so the
instruction reads as evidence rather than as generic caution.
Premature documentation of experimental features, 3 interventions.
The old guidance was a single bullet asking for `Hidden: true`.
Replaced with an explicit readiness gate listing the signals to check
in source (hidden commands, default-off flags, experimental naming,
unserved CRD versions, upstream labels) and what to do when one
fires: don't document, record the deferral in SUMMARY.md so the
completeness pass reads it as a decision, and don't leave a
"coming soon" note behind.
Factual errors, 5 interventions. Three specific root causes now have
their own verification rules: a PR body's claims about absence
("not wired up", "not yet supported") are the least reliable thing
in it because a later commit in the same release silently falsifies
them; a release removes user-facing surface as well as adding it, and
removals never appear in a feature list; and command strings must
trace to their actual registration rather than being inferred from
sibling commands.
Information architecture, 1 intervention. New pages now need at
least one inbound prose link from a page readers reach first. A
sidebars.ts entry satisfies navigation, not the journey.
The fourth mode, editorial and dedup trims, is already what the
Phase 5 docs-review pass is for.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the autogen-docs release workflow to (1) resolve and assign a single “release owner” responsible for driving the PR to merge, and (2) reduce noisy review requests by requesting reviews only from contributors whose changes were classified as docs-facing (with a safe fallback to current behavior when classification is missing/unusable). It also updates the Slack notification pipeline and the upstream-release-docs skill contract to support the new owner + reviewer classification flow.
Changes:
- Add a “resolve release owner and contributors” step that writes
.release-meta.json, and use it to assign the owner as PR assignee/reviewer. - Consume
REVIEWERS.json(written by the skill) to request reviews only from docs-facing contributors; list non-docs-facing contributors as FYI without requesting review. - Restructure the Slack notification prompt + deterministic Slack poster to name the owner first, then requested reviewers, then a single FYI line.
Reviewed changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
.gitignore | Ignore new workflow/skill handoff artifacts (REVIEWERS.json, .release-meta.json). |
.github/workflows/upstream-release-docs.yml | Resolve owner + contributor candidates before the skill, assign owner, and request reviews based on REVIEWERS.json classification with fallback behavior. |
.github/workflows/autogen-docs-notify.yml | Update the Claude prompt schema to extract owner/assignees and no-docs-impact contributors from the PR. |
.github/scripts/post_autogen_docs_slack.py | Deterministically format the Slack message with fixed owner/no-impact wording and updated layout. |
.claude/skills/upstream-release-docs/SKILL.md | Define the new unattended artifact contract for REVIEWERS.json and add guidance supporting contributor classification and ownership. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Unify the bot filter. The contributor compare had its own copy of the bot regex, missing the `^app/` case that is_bot() carries. Both now go through is_bot(), which documents why two bot spellings are needed: the REST compare endpoint returns `renovate[bot]` while gh pr view and gh release view return `app/toolhive-release-app`. No behavior change. The REST compare endpoint only ever emits the `[bot]` suffix form, so the old filter already caught App identities there; verified the candidate list is byte-identical for toolhive v0.43.0 (13 contributors) and toolhive-studio v0.39.4. Fix an inaccurate claim in the Slack composer prompt. It described the owner as the PR assignee, which the workflow knowingly breaks: when GitHub rejects the assignment the owner is still named in the PR body's Owner row, which now reads as the authoritative source. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
rdimitrov
approved these changes
Aug 24, 2026
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 freeto 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.
Description
Autogen-docs PRs were review-then-merge-by-committee with no clear owner. Since July 1, only 2 of 10
toolhivedocs PRs had every requested reviewer approve within the 2-business-day SLO, and PRs stalled for days while later releases queued behind them. Separately, 38% of these PRs needed a post-generation correction (60% fortoolhive), and the causes repeat.Two commits, addressing ownership and generation quality separately.
Assign a release owner. A new step resolves whoever cut the upstream release and sets them as the PR assignee as well as a reviewer; they collect the remaining approvals and merge.
release.authoris unreliable for this (it returns the release App fortoolhiveandtoolhive-registry-server), so resolution falls back to the merger of the upstream release PR, then the tagged commit's author. Verified against 14 releases: for everytoolhiverelease since July 1, the release PR merger is the same person who dispatchedCreate Release PR.Stop requesting reviews nobody needs. The skill now classifies each release contributor as docs-facing or not, from the diffs it already reads in Phase 2, and writes
REVIEWERS.json. Contributors with no reader-visible changes get no review request; they are named on one cc line in the PR body and one line in the Slack message, asking them to speak up if the call was wrong. The owner is always requested regardless of classification. A missing, unparseable, or stubREVIEWERS.jsonfalls back to requesting everyone, so losing the classification degrades to current behavior rather than to silence.Slack message restructured around the same idea: owner and their duty first, then one short line per reviewer, then a single consolidated FYI line. The owner-duty and FYI wording is fixed in the poster script rather than composed per release, so it stays consistent and short.
Skill hardening for the four intervention causes, each citing the release that hit it:
sidebars.tsentry is navigation, not a journey.Type of change
Related issues/PRs
Prompted by the docs review SLO discussion in #documentation. The
Augment PR bodystep is now 313 lines of inline bash; #1112 tracks extracting the fat steps intoscripts/upstream-release/.Screenshots
Rendered PR body section (from the real augment step, with sample env):
Slack message (from the real poster script):
Submitter checklist
Content and formatting
Reviewer checklist
Content
Testing
No live run yet;
REVIEWERS.jsonhas never been produced by a real invocation, and the nexttoolhiverelease PR is the real test. What was verified locally:shellcheckclean on all three new or modifiedrunblocks (extracted from the YAML with${{ }}stubbed).bash -e -o pipefailacross 7 cases: classified, noREVIEWERS.json, stub file, all-contributors-non-docs-facing, no owner resolved, GitHub rejecting the owner assignment and a reviewer, and an empty release range. No case fails the step.jerm-dro(v0.43.0),samuv(v0.42.0),samuv(studio v0.39.4, via the release-author branch),rdimitrov(registry v1.5.1).