Check the Docs line in pull request bodies - #50
Merged
Merged
Conversation
CONTRIBUTING.md asks each pull request body for one line, "Docs: updated X" or "Docs: none, because ...", but nothing checked it. When Kubernetes left a similar docs field unchecked, 92% of the 1,146 pull requests in its 1.37 release left it missing, empty, or a placeholder. The check needs no permissions or checkout and skips bot authors such as Dependabot. It fails when the line is missing, names nothing, or keeps the template placeholder. A line inside an HTML comment does not count, because GitHub hides it. The same file runs in firstdraft/cli and firstdraft/skills. The Docs line, the review steps, and the new Maintenance section now use the service repository's wording, so the three CONTRIBUTING.md pages keep one set of shared rules. Diff-level review questions scored near chance (arXiv 2609.25130), while questions about named claims worked, so the author now names the claims a change affects. The owner prunes instructions and checks at each model release or quarterly, in all three repositories.
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
1 participant
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
The shared contributor rules ask for a
Docs:line in every pull request body, but nothing checked it. Kubernetes measured an unenforced docs field decaying to 92% empty or placeholder. The service repository adds the same check alongside this change.What changed
.github/workflows/pr-docs-line.ymlfails until the body hasDocs: updated XorDocs: none, because .... It rejects the unedited template, skips bot-opened PRs, and reads the body through the environment.CONTRIBUTING.mdnow carries the shared named-claims review step, the Docs-line sentence and the Maintenance section, matching the service repository.Docs: updated CONTRIBUTING.md.
Review
Review: codex-review 0.7.3, high effort, session
1a6bdb0f-b28b-40bb-8ca0-8a5b9d60f65a, approve.