jesseleite/dotfiles/draft-pr

Instructions

When asked to write a PR description, follow these steps:

1. Identify a PR title (usually from the associated Linear issue's diff)
2. Identify the base branch (usually main or master)
3. Run git log --oneline <base>..HEAD to understand the full commit history
4. Run git diff <base>...HEAD --stat for a high-level summary of files changed
5. Run git diff <base>...HEAD to read through the actual changes
6. Draft a PR description using the format below

PR Description Format

## Summary
 
<1-3 sentences explaining what this PR does and why>
 
## New
 
<Optional — Any changes that add functionality of any kind. Omit this section entirely if there's nothing noteworthy.>
 
## Improved
 
<Optional — Any changes that improve functionality. Maybe somethign is not new per se, but is a code quality improvement or some kind of cleanup. Omit this section entirely if there's nothing noteworthy.>
 
## Fixed
 
<Optional — Any changes that improve functionality. Maybe somethign is not new per se, but is a code quality improvement or some kind of cleanup. Omit this section entirely if there's nothing noteworthy.>
 
## Additional Notes
 
<Optional — anything reviewers should know re: follow-up work, breaking changes, related issues, etc. Omit this section entirely if there's nothing noteworthy.>
 
## Manual Testing
 
<Optional — any specific steps reviewers should take to manually test, or any notes about testing considerations.>

Guidelines

• PR title:
• Add the Linear ticket number (ie. (SC-####)) to the end of the title in parentheses
• Summary section:
• The summary should focus on why, not just what
• Don't break lines to specific lengths, let them wrap naturally
• Changes sections (ie. 'New', 'Improved', 'Fixed'):
• If the PR title starts with Fix or the PR looks like a bugfix, show the 'Fixed' section above the other changes sections
• Don't list every file touched; highlight what matters to a reviewer
• Group changes by logical concern in a high-level human-readable fashion, not by file or commit
• Nest bullet points where it makes sense
• Keep it scannable — prefer bullet points over paragraphs
• All bullet points should be 100 characters or less — keep it short and sweet
• All bullet points should be checkboxes (ie. - [x])
• Except for 'Additional Notes' section bullet points, since these are completed changes, but rather just notes
• Where possible, start each bullet point with singular verb (ie. Add ___, Ensure ___, Fix ___, etc.)
• When it comes to bullet points for test coverage:
• Don't consider these bullet points as 'New' section items
• Don't get too granular with these bullet points
• Keep these bullet points super generic (ie. 'Add test coverage' or 'Fleshed out test coverage')
• Additional Notes section:
• If there are breaking changes, call them out here
• If there are related issues or tickets, link them here
• If there is anything else noteworthy in the Linear ticket itself, include it here
• Omit sections that would be empty — don't include placeholder text

Examples

Here are some examples of well written and structured PRs and their associated Linear issues:

• PR #2375 for SC-3091
• PR #2372 for SC-3080
• PR #2369 for SC-3075
• PR #2361 for SC-3068