Software development templates
Pull requests, code reviews, commits, bug reports, design docs, READMEs and engineering communication. 89 free templates, 18 of them longer notes. Open one to fill in the blanks and copy it.
Pull requests
PR descriptions reviewers love.
- PR description Snippet Full template. What Why How Testing - [ ] Unit tests - [ ] Manual test: Screenshots Risks
- Small PR description Snippet Short change. [Summary]. Fixes [Issue]. Tested: [How tested]
- Refactor PR Snippet No behaviour change. Refactor only; no behaviour change. - All existing tests pass.
- Dependency bump PR Snippet Updates a library. Bumps [Package] from [Old] to [New]. Changelog: [Link] Breaking changes: None
- Hotfix PR Snippet Urgent fix. 🔥 Hotfix for [Incident]. Cause: [Cause] Fix: [Fix] Follow-up ticket: [Ticket]
- Feature flag PR Snippet Behind a flag. Adds [Feature] behind the `[Flag]` flag (off by default). To test: enable the flag in [Where].
- Database migration PR Snippet Schema change. Migration: [Change] - Backwards compatible: Yes - Rollback: [Rollback] - Estimated run time: [time now]
- Draft PR note Snippet Work in progress. 🚧 Draft: looking for early feedback on [Approach]. Not ready to merge.
- PR ready for review Snippet Requests review. @[Reviewer] ready for review when you have a moment. The interesting part is [File].
- Stacked PR note Snippet Part of a series. Part [Part] of [Total] for [Feature]. Depends on #[Previous PR].
Code review comments
Kind, clear review comments.
- Suggestion Snippet Optional improvement. Suggestion: Not blocking.
- Question Snippet Ask, do not assume. Question: What happens here when [Case]?
- Nit Snippet Tiny style point. Nit:
- Blocking issue Snippet Must fix before merge. Blocking: [Issue]. This would [Consequence]. Could we [Fix]?
- Praise Snippet Call out good work. Nice! [What] makes this much easier to follow.
- Needs a test Snippet Asks for coverage. Could we add a test for [Case]? It is the path most likely to break later.
- Naming comment Snippet Better names. Nit: `[Name]` could be `[Better name]`, so it says what it holds.
- Security concern Snippet Flags risk. Blocking: this passes user input to [Sink] without escaping, which opens [Risk]. Please use [Safe API].
- Performance note Snippet Flags a slow path. This runs [Operation] inside a loop, so it is O(n²) for [Data]. Could we build a lookup first?
- Approve with comments Snippet LGTM plus notes. Looks good to me! A couple of small comments, none blocking. ✅
- Request changes summary Snippet Overall summary. Thanks for this! Requesting changes for [Main issue]. Everything else is minor.
- Out of scope Snippet Move it to later. Good idea, but out of scope for this PR. Could you open a ticket for it?
Commits and branches
Messages that explain why.
- Conventional commit Snippet Type, scope, summary. feat([Scope]): [Summary]
- Commit with body Snippet Summary plus why. [Summary] [Why] Refs: [Ticket]
- Revert commit Snippet Reverts a change. Revert "[Original]" This reverts commit [Hash] because [Reason].
- Breaking change commit Snippet Marks a breaking change. feat!: [Summary] BREAKING CHANGE: [What breaks]. Migrate by [Migration].
- Co-authored commit Snippet Credits pair programming. [Summary] Co-authored-by: [Name] <[Email]>
- Branch name Snippet Consistent naming. feature/[Ticket]-[short-description]
- Release tag message Snippet Annotated tag. Release [Version] -
- WIP commit Snippet Save point. wip: [What] (squash before merge)
Bug reports and issues
Issues that get fixed.
- Bug report Snippet Full bug template. Summary: [Summary] Steps to reproduce 1. Expected: Actual: Environment: [Environment] Frequency: Always Logs:
- Feature request issue Snippet Requests a feature. Problem: [Problem] Proposed solution: [Solution] Alternatives considered: [Alternatives]
- Technical debt ticket Snippet Records debt. Area: [Area] Debt: [Debt] Cost of leaving it: [Cost] Suggested fix: [Fix] Effort: S
- Spike ticket Snippet Time-boxed research. Question: [Question] Time box: [time now] Output: a short write-up with a recommendation.
- Flaky test ticket Snippet Unreliable test. Test `[Test]` fails about [Rate] of runs on [CI]. Last failure: [Link]. Suspect: [Suspect].
- Cannot reproduce reply Snippet Asks for more detail. Thanks for the report! I could not reproduce this on [Setup]. Could you share [Detail] and whether it still…
- Duplicate issue reply Snippet Links the original. Thanks! This looks like a duplicate of #[Issue], so I will close this one. Follow that issue for updates.
- Good first issue Snippet Welcomes contributors. Good first issue 🌱 [Description] Where to look: `[File]` Help: ask in [Channel].
- Issue triage comment Snippet Labels and prioritises. Triage: P0, bug. Assigned to [Owner].
Engineering docs
Design docs, READMEs and ADRs.
- Design doc Note Technical design. Author: [Author] Status: Draft Context Goals and non-goals Proposed design Alternatives considered Risks…
- Architecture decision record Note ADR format. Status: Proposed Date: [today] Context Decision Consequences
- README Note Project README. [Project] [One-line description] Install bash Usage Configuration Contributing License [License]
- API endpoint doc Note Documents one endpoint. GET [Path] [Description] Parameters | Name | Type | Required | Description | | | | | | | | | | | Response…
- Onboarding guide for engineers Note Setup for new devs. Get the code Run it locally Run the tests Deploy Who to ask
- Postmortem Note Blameless incident review. Incident: [Incident] Severity: SEV1 Duration: [Duration] Summary Timeline - Root cause What went well Action…
- Tech spike write-up Note Findings from research. Question: [Question] Options 1. Findings Recommendation
- Code review checklist Note What to check. - [ ] Does it do what the ticket says? - [ ] Tests cover the new paths - [ ] Errors handled - [ ] No secrets…
- Release checklist Note Before a release. - [ ] Version bumped to [Version] - [ ] Changelog updated - [ ] Tests green - [ ] Staging verified - [ ]…
- Debugging log Note Track a hard bug. Bug: [Bug] Hypotheses - [ ] Tried - Findings Fix
- Contributing guide Note How to contribute. Contributing to [Project] 1. Fork and clone 2. Create a branch 3. Make changes with tests 4. Open a pull…
- Tech debt inventory Note List the debt. | Area | Problem | Impact | Effort | Owner | | | | | | | | | | | | |
Engineering communication
Updates to people outside engineering.
- Deploy announcement Snippet Tells the team. 🚀 Deployed [Service] [Version] to production. Changes: [Changes].
- Estimate reply Snippet Gives an honest estimate. My estimate for [Task] is [Estimate], with [Confidence] confidence. Biggest unknown: [Unknown].
- Explain a delay Snippet To a non-technical stakeholder. Hi [Name], [Feature] will take longer than planned. In plain terms: [Plain explanation]. New estimate: [New…
- On-call handover Snippet Rotation handover. On-call handover for [Week] Open incidents: [Incidents] Things to watch: [Watch] Noisy alerts: [Alerts]
- Code freeze notice Snippet Before a release. Code freeze for [Release] starts [today] at [time now]. Only critical fixes merge after that, with approval…
- Interview feedback engineer Snippet Technical interview notes. Candidate: [Candidate] Problem: [Problem] Strengths: [Strengths] Concerns: [Concerns] Recommendation: Strong…
- Open source thank-you Snippet Thanks a maintainer. Thank you for maintaining [Project]! It saves our team [Benefit]. We have started sponsoring you.
Open source maintainers
Issues, PRs and community.
- Thank a contributor Snippet Merged PR thanks. Thanks so much for this, @[User]! Merged and it will ship in [Version]. 🎉
- Needs reproduction Snippet Ask for a repro. Thanks for the report! Could you share a minimal reproduction (a small repo or snippet)? That helps us fix…
- Closing stale issue Snippet Stale issue. Closing this as there has been no activity for 60 days. Please reopen with more details if it is still an…
- Feature out of scope Snippet Decline a feature. Thanks for the suggestion! This is outside the scope of [Project], which focuses on [Focus]. A plugin could…
- Security report redirect Snippet Private disclosure. Thanks for reporting! Please do not post security issues publicly; email [Security email] instead so we can…
- Release announcement OSS Snippet New version. [Project] [Version] is out! Highlights: - Thank you to everyone who contributed.
- Code of conduct reminder OSS Snippet Keep it respectful. Please keep discussion respectful and on topic, per our code of conduct: [Link].
- Sponsorship ask Snippet Support the project. If [Project] saves you time, please consider sponsoring its maintenance: [Link]
Engineering updates
Tell others what engineering did.
- Monthly engineering update Snippet For the company. Engineering update, [today] Shipped: [Shipped] In progress: [In progress] Reliability: [Reliability]…
- Tech debt proposal Snippet Pitch cleanup work. Proposal: spend [time now] on [Debt]. Why: [Why] Cost of not doing it: [Cost] Plan: [Plan]
- Migration announcement Snippet Moving systems. We are migrating [Old] to [New] on [today]. What changes: [Changes]. What you need to do: [Action].
- API deprecation notice Snippet Retire an endpoint. The [Endpoint] endpoint is deprecated and will be removed on [today]. Please switch to [Replacement]. Guide:…
- Security patch notice Snippet Urgent update. A security fix for [Component] is available in [Version]. Please update by [in 7 days].
- Hackathon announcement Snippet Internal hack week. Hack week is [Dates]! Theme: [Theme]. Pitch ideas in [Channel] by [Deadline].
Engineering notes
Everyday engineering docs.
- Pull request checklist note Note Personal checklist. - [ ] Self-reviewed the diff - [ ] Tests added - [ ] Docs updated - [ ] No debug logs - [ ] Screenshots for UI
- Incident timeline Note Live incident log. | Time (UTC) | Event | Who | | | | | | [time now] | | |
- Architecture overview Note System map. Components Data flow Dependencies Scaling limits Owners
- Estimation notes Note Break down an estimate. | Task | Best | Likely | Worst | | | | | | | | | | | Total likely:
- Learning notes tech Note New technology. Tech: [Tech] What it is When to use it Gotchas Links
- Environment setup notes Note Local setup. Prerequisites Install Env variables Run Common problems
Commit message examples
Good commits by type.
- fix: typo Snippet Typo fix. fix(docs): correct typo in [File]
- feat: add endpoint Snippet New endpoint. feat(api): add [Method] [Path] endpoint
- fix: null crash Snippet Crash fix. fix([Scope]): handle missing [Value] to prevent crash
- perf: cache Snippet Performance. perf([Scope]): cache [What] to cut load time
- refactor: extract Snippet Refactor. refactor([Scope]): extract [Thing] into its own module
- test: add coverage Snippet Tests. test([Scope]): cover [Case]
- chore: bump deps Snippet Dependencies. chore(deps): bump [Package] to [Version]
- ci: workflow Snippet CI change. ci: run [Job] on pull requests
- docs: readme Snippet Docs update. docs: explain how to [Task] in README
- style: format Snippet Formatting. style: format [Files] with [Formatter]
- revert: change Snippet Revert. revert: "[Original]"