Writing effective commit messages

Commit messages are the primary means of documenting changes in a codebase. They facilitate understanding of the project's history, aid in debugging, and enhance collaboration among team members. Clear and consistent commit messages are especially crucial during code reviews and when utilizing tools like Graphite, which rely on well-structured commits to manage stacked pull requests effectively.

Structure of a good commit message

A well-crafted commit message typically consists of three parts:

1. Header: A concise summary of the change, ideally under 50 characters.
2. Body (optional): A detailed explanation of what and why the change was made.
3. Footer (optional): References to related issues or breaking changes.

Example:

feat(auth): add OAuth2 login support

Implement OAuth2 authentication flow with Google and GitHub providers.
This change allows users to log in using their existing accounts
without creating new credentials.

Closes #123, Relates to #456

Commit message best practices

• Use the imperative mood: Start the header with a verb in the imperative mood, e.g., "add," "fix," "update." This aligns with the convention that the message completes the sentence "If applied, this commit will...".
• Keep it concise: Limit the header to 50 characters. If more detail is needed, use the body section.
• Separate header from body: Insert a blank line between the header and body to improve readability.
• Wrap the body at 72 characters: This ensures better readability in various interfaces.
• Explain the "what" and "why": Focus on what the change does and why it was made, rather than how it was implemented.
• Reference issues and pull requests: Use the footer to link related issues or PRs, which aids in tracking and automation.

Git commit message guidelines

Adhering to established guidelines ensures consistency across the project:

• Avoid punctuation in headers: Do not end the header with a period.
• Use lowercase in headers: Unless a proper noun is used, keep the header in lowercase.
• Be descriptive: Avoid vague messages like "update" or "fix." Instead, specify what was updated or fixed.
• Use semantic prefixes: Incorporate prefixes like "feat," "fix," "docs," etc., to categorize the nature of the change.

Semantic commit messages

Semantic commit messages follow a structured format that facilitates automation and clarity:

<type>(<scope>): <subject>

• Type: Describes the nature of the change (e.g., feat, fix, docs, style, refactor, test, chore).
• Scope: Specifies the area of the codebase affected (e.g., auth, api, ui).
• Subject: A brief description of the change.

Examples:

• feat(api): add user profile endpoint
• fix(ui): resolve button alignment issue
• docs(readme): update installation instructions

This convention supports tools like semantic-release, which automate versioning and changelog generation based on commit messages.

Integrating with Graphite for code reviews

Graphite enhances the code review process by managing stacked pull requests efficiently. Clear and well-structured commit messages are vital when using Graphite, as they:

• Facilitate reviewer understanding: Descriptive messages help reviewers grasp the purpose of each commit quickly.
• Support stacked diffs: In a stacked PR workflow, each commit builds upon the previous one. Clear messages ensure that each layer is understandable in isolation.
• Enable automation: Consistent commit messages allow Graphite to automate aspects of the review and merge process effectively.

Best practices with Graphite:

• Maintain logical commits: Each commit should represent a single logical change.
• Use clear scopes: When applicable, specify the scope in your commit messages to indicate the affected area.
• Reference related issues: Link to relevant issues or tasks to provide context.

Conclusion

Effective commit messages are a cornerstone of collaborative software development. By following best practices and adopting semantic conventions, developers can create a clear and maintainable project history. Tools like Graphite further amplify these benefits by streamlining the code review process through structured commits. For teams looking to scale their development practices, consider reading our guide on streamlining pull request process automation to learn how to optimize your entire development workflow.