How to write good commit messages and pull requests — a team guide

Rizwan Saleem Posted on May 30 How to write good commit messages and pull requests — a team guide # webdev # ai # frontend How to write good commit messages and pull requests — a team guide This will be a practical, structured post focused on clarity, consistency, and real-world examples. Clear commit messages and pull requests are not just “nice to have”-they directly affect how fast your team can review, debug, and ship. When done well, they turn your version history into documentation. When done poorly, they create friction and confusion. Why this matters A good commit history answers three questions quickly: What changed? Why did it change? How does it relate to the rest of the work? A strong pull request (PR) answers: What problem is being solved? How was it solved? What should reviewers focus on? If your teammates can answer those without asking you, you are doing it right. Writing clear commit messages Use a consistent structure A widely adopted format is Conventional Commits: <type>(optional-scope): short summary Common types: feat: New feature fix: Bug fix refactor: Code change without behavior change chore: Maintenance (deps, configs) docs: Documentation test: Tests Example: feat(auth): add password reset via email Keep the summary tight Use present tense: “add”, not “added” Keep it under ~72 characters Focus on what, not how Bad: fixed stuff Better: fix(cart): prevent duplicate items on rapid click ### Writing descriptive commit bodies Use the body when the change is not obvious. Structure: Why the change was needed What approach was taken Any trade-offs or edge cases Example: fix(cart): prevent duplicate items on rapid click Users could add the same item multiple times by clicking quickly before the UI updated. This introduces a temporary client-side lock while the add-to-cart request is in flight. Does not yet handle server-side race conditions. Enter fullscreen mode Exit fullscreen mode Link commits to issues Always connect work to a ticket or is