Why Should We Care About Git Commit Messages and PR Descriptions?

Real-world example:

Imagine this scenario: your team discovers a critical bug in your production environment. This bug is traced back to a change made by a developer who is no longer with the company. To resolve the issue, you need to adjust a SQL query file. The catch? You have no idea why this change was made in the first place. The commit message, PR description, ticket description, and even the code itself offer no clues. You're left scratching your head.

The result? Countless hours spent deciphering the change and fixing the bug. However, if the commit message, PR description, ticket description, and code were well-documented, you could resolve the issue swiftly.

So, What Makes a Good Commit Message and PR Description?

While there's no rigid standard for good commit messages and PR descriptions, following these guidelines can significantly improve your documentation:

1. Be Self-Documenting, Descriptive, and Concise: Your commit message and PR description should explain the change without requiring readers to dive into the code. Clearly state the reason behind the change and the technical decisions involved in a brief and clear manner.

2. Ideal Structure:

Commit Message

[branch-name]: <commit-message> Describe your changes briefly

<commit-description> Provide detailed information about the commit, including:
   <pre-commit-description> Explain the problem this commit addresses
   <commit-changes> Detail the changes made in this commit
   <post-commit-description> Describe the impact of this commit

Example:

PR Description

[branch-name]: <PR-title> Describe your changes briefly

<PR-description> Provide detailed information about the PR, including:
    <pre-PR-description> Explain the problem this PR addresses
    <PR-changes> Detail the changes made in this PR
    <post-PR-description> Describe the impact of this PR

1. Focus on a Single Aspect: Each commit should centre on a single technical decision. If a change is linked to a ticket, the commit shouldn't include the ticket description, as that focuses on product and feature details, not the technical decision. Avoid duplicating code in the commit message, since the code is self-documenting.

2. Squash Multiple Commits: When multiple commits are required for a change, consolidate them into one commit before merging into the main branch. Update the commit message and PR description to reflect the change.

3. Split Multiple Changes: If a ticket involves multiple changes, separate them into distinct commits. Each commit should address one technical decision, and accordingly, the commit message and PR description should be updated.

Incorporating these guidelines into your Git workflow will enhance clarity, save time, and make it easier to maintain your codebase.