Development Workflow

Write Useful and Reviewable Git Commit Messages

Create commit history that explains intent, isolates changes, and supports debugging and release notes.

A commit is a durable explanation of a change. Good commit messages help reviewers understand intent and help future maintainers identify why a behavior changed.

Describe the purpose

The subject line should summarize the change in imperative or consistent team style. Keep it concise and specific: “Reject expired preview tokens” communicates more than “Fix security issue.”

Use the body to explain context, constraints, and relevant tradeoffs. Describe why the change was needed rather than repeating the diff line by line.

Keep commits coherent

A commit should represent one logical unit that can be reviewed and, where practical, reverted independently. Avoid mixing formatting, dependency updates, unrelated fixes, and feature work in one commit.

Do not split changes so aggressively that intermediate commits cannot build or tests cannot run unless the team explicitly accepts that tradeoff.

Reference work carefully

Issue identifiers and links can connect code history to decisions. Avoid putting secrets, personal information, or confidential customer details in commit messages because repository history is persistent and widely replicated.

Checklist

  • Explain the intent in the subject.
  • Add context when the reason is not obvious.
  • Keep unrelated changes in separate commits.
  • Use consistent issue references.
  • Never include credentials or private data.
Share this page Help other developers discover this resource.