mirror of
https://github.com/vercel/eve.git
synced 2026-09-20 05:35:39 +08:00
chore(skills) lead PR descriptions with the reason for change and simplify skill (#2956)
Signed-off-by: Colton Padden <colton.padden@vercel.com>
This commit is contained in:
Colton Padden
@@ -5,157 +5,31 @@ description: Drafts and reviews GitHub pull request descriptions for the eve rep
|
||||
|
||||
# GitHub PR description
|
||||
|
||||
See [review notes](references/review-notes.md) for the maintainer patterns behind
|
||||
this workflow; they describe what to cover, not how much to write.
|
||||
Inspect the branch diff, commits, related issue or discussion, tests, docs, and
|
||||
changesets. When updating a PR, read its current body first.
|
||||
|
||||
Read `CONTRIBUTING.md` and `.github/pull_request_template.md`, then inspect the
|
||||
branch diff, commits, related issue, tests, docs, and changesets. If updating a
|
||||
PR, read its current body too.
|
||||
## Write
|
||||
|
||||
Fill in the repository template. Write for a reviewer:
|
||||
Fill in `.github/pull_request_template.md`. Write for a reviewer, not a
|
||||
changelog:
|
||||
|
||||
- explain the concrete problem and solution near the top
|
||||
- summarize meaningful behavior and decisions, not files or commits
|
||||
- mention breaking changes, preserved behavior, scope boundaries, or stacked
|
||||
PRs only when relevant
|
||||
- link a prior issue or discussion with `Closes #N`, `Related to #N`, or
|
||||
equivalent when one exists; never create an issue solely for the PR
|
||||
- scale length with risk, not diff size
|
||||
- Keep the Summary to one short paragraph: usually 2–4 sentences and about
|
||||
100 words or fewer.
|
||||
- Lead with the concrete problem, user need, or decision behind the change;
|
||||
follow with the solution and meaningful behavior. Prefer short sentences;
|
||||
split independent points rather than combining them into a long sentence.
|
||||
- Do not list files or narrate commits. Include implementation detail only when
|
||||
it is necessary to assess behavior or risk.
|
||||
- Mention breaking changes, preserved behavior, tradeoffs, scope boundaries,
|
||||
follow-ups, or stacked PRs only when they matter to review.
|
||||
- Link an existing issue or discussion with `Closes #N`, `Related to #N`, or an
|
||||
equivalent when one exists. Do not create an issue solely for a PR.
|
||||
- State only validation that actually ran, including limitations or failures.
|
||||
|
||||
Append a `### Diff size` section after the template checklist. This must be the
|
||||
last section of every PR description and must account for every changed file in
|
||||
exactly one of these categories:
|
||||
Preserve the checklist and check only verified items.
|
||||
|
||||
- **Docs** — documentation, research, changesets, and other prose or release
|
||||
metadata
|
||||
- **Implementation** — product code, configuration, dependencies, build files,
|
||||
and generated runtime artifacts
|
||||
- **Tests** — tests, evals, test-only fixtures, and snapshots
|
||||
## Publish
|
||||
|
||||
Use three full-width category blocks in the order above, including categories
|
||||
with no changes. Do not use a table: the overview and any reviewer-relevant
|
||||
context need the full description width to remain readable on GitHub.
|
||||
|
||||
```markdown
|
||||
### Diff size
|
||||
|
||||
**Docs** — 0 files · `+0 / -0`
|
||||
|
||||
Not applicable.
|
||||
|
||||
**Implementation** — 1 file · `+12 / -4`
|
||||
|
||||
Focused implementation of the behavior above.
|
||||
|
||||
**Tests** — 1 file · `+28 / -0`
|
||||
|
||||
Regression coverage for success and failure paths.
|
||||
```
|
||||
|
||||
Keep each category's file count, additions, and deletions visible on its bold
|
||||
heading line. Treat the section as an overview, not a file inventory: do not
|
||||
list every changed path. Mention individual files only when they are critical
|
||||
to understanding or reviewing the change, under a short `Key files` list. Omit
|
||||
paths entirely when no file needs special attention. The category counts must
|
||||
still include every changed file. Do not collapse the category totals or the
|
||||
entire Diff size section.
|
||||
|
||||
Report additions and deletions from the full branch diff against the PR base,
|
||||
and verify that the three categories reconcile with the complete diff. Note
|
||||
binary files separately instead of treating them as zero-line changes. Classify
|
||||
a mixed-purpose file by its primary purpose; mention that ambiguity only when it
|
||||
is useful to the reviewer.
|
||||
|
||||
The justification must explain why each category needs that amount of change,
|
||||
not merely restate its line count. Call out a file or category only when its
|
||||
size is genuinely surprising or materially disproportionate to the behavior
|
||||
and review scope, especially for generated files, snapshots, fixtures, or
|
||||
mechanical changes. Being the only changed file, the largest category, or a
|
||||
modest one-file diff does not make something an outlier.
|
||||
|
||||
Keep a concise explanation visible. If supporting detail would be lengthy, use
|
||||
a category-local `<details>` block with a specific, natural summary such as
|
||||
`Generated output`, `Fixture expansion`, or `Mechanical migration`; do not use
|
||||
a prescribed heading or force words such as `unusually`. Explain why the large
|
||||
portion is necessary and could not reasonably be smaller. If the size is
|
||||
surprising for the stated behavior, flag it for reviewer attention rather than
|
||||
normalizing it. Do not manufacture an outlier explanation for an ordinary diff.
|
||||
The rest of the description should still discuss behavior rather than enumerate
|
||||
files; this section is the required exception.
|
||||
|
||||
```markdown
|
||||
Generated output accounts for most of the implementation diff.
|
||||
|
||||
<details>
|
||||
<summary>Generated output</summary>
|
||||
|
||||
Explain why the generated changes are necessary and could not reasonably be
|
||||
smaller.
|
||||
|
||||
</details>
|
||||
```
|
||||
|
||||
Default to the shortest body that answers the five questions below. Keep the
|
||||
Summary under 5 sentences for most PRs; exceed 10 lines only for breaking or
|
||||
cross-cutting changes. Prefer plain language. Include implementation detail or
|
||||
jargon only when the reviewer cannot assess behavior or risk without it. Do not
|
||||
restate the issue, template guidance, or checklist. Use bullets only when they
|
||||
improve clarity.
|
||||
|
||||
A typical small PR body:
|
||||
|
||||
```markdown
|
||||
### Summary
|
||||
|
||||
Closes #412. `eve dev` crashed when an agent had no `connections/` directory;
|
||||
the compiler now treats missing optional directories as empty.
|
||||
|
||||
### Validation
|
||||
|
||||
Reproduced the crash with the weather fixture and confirmed the fix with
|
||||
focused regression coverage.
|
||||
|
||||
### Checklist
|
||||
|
||||
(preserved from the template; only verified items checked)
|
||||
|
||||
### Diff size
|
||||
|
||||
**Docs** — 0 files · `+0 / -0`
|
||||
|
||||
Not applicable.
|
||||
|
||||
**Implementation** — 1 file · `+6 / -2`
|
||||
|
||||
Keeps the missing-directory handling local to the compiler.
|
||||
|
||||
**Tests** — 1 file · `+14 / -0`
|
||||
|
||||
Covers the regression without broad fixture changes.
|
||||
```
|
||||
|
||||
Under validation, write one short prose description, not a bullet list of
|
||||
commands. For a bug fix, say what was reproduced and how the fix was
|
||||
confirmed. For a feature, say how coverage demonstrates the new behavior. Do
|
||||
not mention routine formatting, linting, type checking, or other baseline
|
||||
checks; CI coverage is assumed. Note limitations honestly and do not claim
|
||||
checks that only CI will run.
|
||||
|
||||
Preserve the checklist and check only verified items. If tests, docs, or a
|
||||
changeset are not applicable, say so in one short line at most.
|
||||
|
||||
Before returning or publishing the description, confirm that it answers:
|
||||
|
||||
1. What problem does this solve?
|
||||
2. What meaningfully changes?
|
||||
3. How was it validated?
|
||||
4. What should the reviewer pay special attention to?
|
||||
5. How is the complete diff divided among docs, implementation, and tests, and
|
||||
why is each category that size?
|
||||
|
||||
Then prune: outside the required Diff size section, delete any sentence that
|
||||
restates the diff, the issue, or the template, and any detail the reviewer does
|
||||
not need. If the answer to question 4 is "nothing," leave it out.
|
||||
|
||||
When asked only to draft, return the body for review. When asked to create or
|
||||
update the PR, pass a body file to `gh pr create` or `gh pr edit`.
|
||||
Before publishing, confirm the Summary leads with why the change is needed.
|
||||
Write the body to a file, then pass it to `gh pr create` or `gh pr edit` with
|
||||
`--body-file`.
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
# PR description review notes
|
||||
|
||||
These guidelines were derived from the five most recent pull request
|
||||
descriptions by Casey Gowrie and Andrew Barba, together with the repository's
|
||||
contributing guidelines and pull request template.
|
||||
|
||||
## What made the descriptions useful
|
||||
|
||||
- **They led with outcomes.** Short summaries made the problem and resulting
|
||||
behavior clear before implementation details.
|
||||
- **They emphasized review-significant details.** Bullets covered public
|
||||
behavior, contracts, design decisions, and regression coverage rather than
|
||||
listing changed files.
|
||||
- **They named boundaries.** Larger changes identified preserved behavior,
|
||||
deliberate non-goals, compatibility implications, and where work belonged in
|
||||
a stack of changes.
|
||||
- **They provided context.** Descriptions identified the related issue or
|
||||
proposal and distinguished closing, related, superseded, and dependent work.
|
||||
- **They gave concrete validation.** Test sections named exact commands,
|
||||
focused suites, pass counts, and manual checks where useful.
|
||||
- **They were candid about limitations.** When local validation was blocked,
|
||||
the description said why and what CI would cover instead.
|
||||
- **They scaled with risk.** Small fixes used a few bullets; broad or breaking
|
||||
changes included enough structure to explain scope and migration impact.
|
||||
- **They accounted for repository obligations.** Tests, documentation,
|
||||
changesets, and cases where those were not applicable were made explicit.
|
||||
|
||||
The resulting standard is reviewer-oriented: explain the problem, meaningful
|
||||
change, validation, and anything that deserves special attention. Avoid file
|
||||
inventories, commit narration, unsupported claims, and boilerplate that does
|
||||
not help review.
|
||||
@@ -1,11 +1,12 @@
|
||||
### Summary
|
||||
|
||||
<!--
|
||||
If an issue or discussion already exists, link it (for example, "Closes #123"
|
||||
or "Related to #123"). Do not create an issue solely to accompany this pull
|
||||
request. Explain the concrete problem and solution, then summarize meaningful
|
||||
behavior or decisions—not changed files or commits. Call out breaking changes,
|
||||
preserved behavior, scope boundaries, or stacked PRs when relevant.
|
||||
Keep this short. Start with the concrete problem, user need, or decision that
|
||||
prompted the change, then explain the solution and meaningful behavior or
|
||||
decisions—not changed files or commits. Link an existing issue or discussion
|
||||
when one exists (for example, "Closes #123" or "Related to #123"). Do not
|
||||
create an issue solely to accompany this pull request. Call out breaking
|
||||
changes, preserved behavior, scope boundaries, or stacked PRs when relevant.
|
||||
-->
|
||||
|
||||
### Validation
|
||||
|
||||
@@ -31,13 +31,14 @@ the DCO `Signed-off-by` trailer. Use `git commit -s` for every commit, and if a
|
||||
commit is missing the trailer, amend it with `git commit --amend -s --no-edit`
|
||||
before pushing.
|
||||
|
||||
PR descriptions are reviewer-oriented explanations of the problem, solution,
|
||||
meaningful behavior changes, and validation—not file lists or commit logs. Keep
|
||||
them proportional to the change, link a prior issue or discussion when one
|
||||
exists, call out important scope boundaries or preserved behavior, and report
|
||||
only checks actually run. Never create an issue solely to accompany a PR. Use the
|
||||
[`gh-pr-description`](./.agents/skills/gh-pr-description/SKILL.md) skill when
|
||||
drafting or updating one.
|
||||
PR descriptions are reviewer-oriented explanations of the problem or decision
|
||||
behind the change, the solution, meaningful behavior changes, and validation—not
|
||||
file lists or commit logs. Keep the Summary short and lead with that
|
||||
justification before implementation details. Link a prior issue or discussion
|
||||
when one exists, call out important scope boundaries or preserved behavior, and
|
||||
report only checks actually run. Never create an issue solely to accompany a PR.
|
||||
Use the [`gh-pr-description`](./.agents/skills/gh-pr-description/SKILL.md)
|
||||
skill when drafting or updating one.
|
||||
|
||||
## Commands
|
||||
|
||||
|
||||
+2
-1
@@ -210,7 +210,8 @@ on when one exists. Do not create an issue solely to accompany a pull request.
|
||||
```
|
||||
|
||||
5. Make sure `pnpm lint`, `pnpm typecheck`, and `pnpm test` pass.
|
||||
6. Open the PR with a clear description of the problem and solution.
|
||||
6. Open the PR with a short description that explains the problem, user need,
|
||||
or decision behind the change before describing the solution.
|
||||
|
||||
Releases are managed with [Changesets](https://github.com/changesets/changesets) by the maintainers.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user