Write better commit messages!

A Pragmatic Approach for Modern Development

Commit messages are mostly useless

In the world of software development, we've long been told that detailed, descriptive commit messages are crucial. But is this still true in the age of modern Git hosting services and collaborative tools? Let's challenge this conventional wisdom and explore a more pragmatic approach to commit messages that aligns with contemporary development practices.

The Case Against Traditional Commit Messages

Why Traditional Commit Messages Fall Short

1. Redundancy: Modern Git hosting services like GitHub, GitLab, and Bitbucket provide superior platforms for discussing code changes.

2. Poor Visibility: Long commit messages are often overlooked and rarely read in full.

3. Inefficient Communication: Important information can get lost in verbose commit histories.

Commit messages will still be useless if we don't adapt our approach to modern workflows!

A New Paradigm for Commit Messages

Let's reimagine commit messages with a focus on efficiency and context. Here's what we really need:

1. State Your Intent Concisely

Keep your commit messages short and to the point. Aim for 10 words or less that clearly state what you've done.

Best Practices:

• Start with an intent flag: fix, feature, enhancement, or refactor

• Use the "enhancement" flag for developer-related improvements (e.g., linting, CI/CD, documentation)

Examples:

• fix/login-screen-validation

• refactor/class-a-to-introduce-endpoint-b

• enhancement/add-eslint-configuration

2. Reference the Issue

Provide context by linking your commit to the original issue or task.

Why This Matters:

• Maintains traceability between code changes and project management

• Allows for easy access to full discussions and requirements

How to Do It:

• Use ref #issue-number in your commit message

• For automatic issue updates, use keywords like close, fix, or resolve (but use these judiciously)

Pro Tip: Prefer manual issue closure to add final remarks and ensure all requirements are met.

3. Save Details for Pull Requests

Leverage the Pull Request (PR) description for in-depth explanations of your changes.

What to Include in PRs:

1. Detailed explanation of what you've changed

2. Rationale behind your changes

3. Bullet points for clarity and brevity

4. Emojis to add visual interest and quick understanding

Remember: PRs are more visible and provide a better platform for discussion than commit messages.

4. Stylistic Preferences for Clarity

While personal style varies, consider these guidelines for clear, consistent commit messages:

1. Start with a verb (past tense often works best)

   • ✅ "Renamed class A to B"

   • ❌ "Rename class A to B"

2. Use bullet points for multiple changes

3. Conclude with the impact: "If applied, this commit will [achieve X]"

By rethinking our approach to commit messages, we can create a more efficient, context-rich development process. This pragmatic approach focuses on concise intent, clear issue references, and leveraging modern tools for detailed discussions. Remember, the goal is to facilitate better communication and understanding among your team, not to write a novel in your commit history.