|
| 1 | +--- |
| 2 | +name: contributor-pr-description |
| 3 | +description: Guidelines and format for writing pull request descriptions in this repository. Use this skill whenever the user asks you to draft a pull request description, submit a PR, or update a PR description. |
| 4 | +metadata: |
| 5 | + internal: true |
| 6 | +--- |
| 7 | + |
| 8 | +# Pull Request Description Guidelines |
| 9 | + |
| 10 | +When writing a pull request (PR) description, your goal is to provide reviewers with enough context to understand what you did, why you did it, and how they can verify it. A good PR description speeds up the review process and serves as documentation for future contributors. |
| 11 | + |
| 12 | +## Identity Verification |
| 13 | + |
| 14 | +If you are in an environment where there are multiple GitHub identities (e.g., an AI agent identity and a primary user identity), **you must verify your identity before pushing or creating a PR**. |
| 15 | + |
| 16 | +Before committing, pushing, or opening a PR, ensure you are using the identity that the user expects based on the type of work and the repository you are working on. Verify your active GitHub CLI auth (`gh auth status`) and ensure your Git commit author (`git commit --author="..."`) matches the correct identity for the task. |
| 17 | + |
| 18 | +## PR Description Template |
| 19 | + |
| 20 | +Always use the following template (or a very similar structure) when drafting a PR description: |
| 21 | + |
| 22 | +```markdown |
| 23 | +## Summary |
| 24 | +[Provide a clear, 1-2 sentence summary of what this PR does.] |
| 25 | + |
| 26 | +## Motivation and Context |
| 27 | +[Explain why this change is necessary. What problem does it solve? If it's a bug fix, what was the broken behavior?] |
| 28 | + |
| 29 | +## Related Issues |
| 30 | +[If this PR fixes an open issue, link to it using keywords. e.g., "Fixes #123" or "Closes #456". If it relates to an issue but doesn't close it, use "Related to #789".] |
| 31 | + |
| 32 | +## What changed |
| 33 | +[Optional: Provide a bulleted list of the most important technical changes made in the code. This is useful for larger PRs.] |
| 34 | +- Added `FooClass` to handle XYZ. |
| 35 | +- Updated `BarMethod` to return `Result`. |
| 36 | + |
| 37 | +## Testing Instructions |
| 38 | +[Explain how reviewers can test your changes locally. Mention any manual verification steps.] |
| 39 | +- Run `dart test` to ensure all tests pass. |
| 40 | +- [Any specific manual testing steps] |
| 41 | + |
| 42 | +``` |
| 43 | + |
| 44 | +## Tone and Style |
| 45 | + |
| 46 | +1. **Be clear and concise**: Avoid rambling. Use bullet points for readability. |
| 47 | +2. **Focus on the "Why"**: The diff shows *what* changed. The description should explain *why* it changed. |
| 48 | +3. **Be professional**: Use natural, accessible language. |
| 49 | + |
| 50 | +## Examples of Bad vs Good Summaries |
| 51 | + |
| 52 | +**Bad**: "Fixed the bug." (Too vague, doesn't explain what bug) |
| 53 | +**Bad**: "Changed line 42 in `main.dart` to use `foo` instead of `bar`." (Focuses too much on the code, which is visible in the diff) |
| 54 | + |
| 55 | +**Good**: "Fixes a crash when the user clicks 'Submit' without entering an email address by adding validation to the input form." (Explains the problem and the solution) |
0 commit comments