Writing Better Commits

Published 03-11-2023

Recently I wrote a lightweight open-source CLI for writing better commits. It helps you follow the Conventional Commit Guideline, while being flexible and configurable.

Source Code on Github

  • Highly flexible configuration
  • Easy install with sane defaults
  • Infers ticket/issue and type from branch
  • Git status & interactive git add
  • Color preview and confirm

But, why write better commits?

A good commit history helps others (and the future you) better understand your code and how it came to be that way.

For myself, writing a good commit is like writing good notes. I want to write it in a way that when I look back I can understand why and how I made the decisions I did.

better-commits and the Conventional Commit Guidelines, provide a way to format commits consistently. Doing so can result in some cool side-effects, aside from making your commits easier to read and understand.

  • Automate versioning from commits with semantic release
  • Automate change logs from commits
  • Automate build processes based on commit
  • Auto reference & close issues to PRs
  • Auto populate the title and body of Github PRs and merge commits.

Examples Commits

Below are a few example commits. These follow the Conventional Commit Guidelines, and may provide some inspiration for writing better commits.

New feature

  • The type of change, scope, github issue, and high-level description are all easily visible.
  • The body explains what changed. Including the property name to enable.
  • The ticket is referenced in the footer, which connects the Github issue with its corresponding pull request.
terminal 
feat(tools): #3 infer ticket/issue from branch

If commit_type.infer_value_from_branch is enabled,
will attempt to infer ticket/issue from branch name.
Updated documentation with details.

Closes: #3

Breaking changes

  • The breaking change is signified by:
    • An exclamation point after the type and before the colon, brings attention to the commit
    • The “BREAKING CHANGE” label explains what the breaking change was.
  • This could be extended to include an optional body. Explaining a path to migrate from Node 6 and resolve the breaking change.
terminal 
chore!: drop Node 6 from testing matrix

BREAKING CHANGE: dropping Node 6 which hits end of life in April

Quick adjustment to documentation

  • Technically a valid conventional commit. Many of the items in the specification are optional or shouldn’t be forced if not applicable.
terminal 
docs: Fix tabbing in defaults section of readme

Conclusion

At my job as a software engineer, I’ve always followed branch and git commit guidelines. However, I’ve ignored maintaining a good commit history in my personal close-sourced projects.

As those projects have grown. I’ve realized that the small increased effort upfront, to write a good commit message, is worth the improved developer experience. — And so I created better-commits. To be able to quickly and easily follow good practices across all of my projects.

If you enjoy using the better-commits CLI, ⭐️ star it on github, so I feel like the special little snowflake my mother tells me I am.

Sat Mar 11 2023