Clean Git: Self-Documented Project

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.

Comments

[Parzival]

Useful for workflow.

[Rusydy]

Thank you

[Fady GA 😎]

Great guidelines! Do you know any tooling that can enforce it? As experience tells us that we can't count only on the user's behavior 🤷🏼‍♂️

[Tiago de Oliveira]

Então uma ferramenta específica pra isso eu não vi não, mas tem como fazer algumas ferramentas funcionarem juntas.

Acredito que isso possa lhe ajudar.

dev.to/boadude/commit-standard-and...

[Rusydy]

As far as I know, there are none.

So, to implement it, the team leader or the most senior developer should be the key player.

[Fady GA 😎]

I' ve played once with Git Hooks. Maybe it can be benificial in this context? Executing a python scripts with regex to check the commit message before commiting to the local repo for example 🤷‍♂️