| id | DEV-340 |
|---|---|
| title | Name a PR for What Users Gain |
| status | active |
| enforcement | manual |
| severity | error |
A technical or vague PR title such as Create player or
Fix: add file to mute sound tells stakeholders nothing about the change. PR
titles communicate to everyone, including non-technical readers.
Name the PR for what a user can now do.
- Follow Conventional Commits:
type(scope): action. - Make it user-focused: describe what users gain, not the implementation. Ask "what will users be able to do?", not "what am I building?" Use action verbs such as View, Play, Customize, Save.
- Keep it present tense and under 65 characters.
- Apply this to all PR types, including
docs. Do not use verbs that describe what you did ("document", "update", "add"); use verbs for what users can now do.
| Good | Bad |
|---|---|
feat(ui): play music |
Create player |
docs(api): authenticate with OAuth |
docs(api): add OAuth section |
- The title follows
type(scope): action - It describes what a user can now do, not the implementation
- It is present tense and under 65 characters
- It holds even for
docsPRs