DEV Community

loading...
Cover image for Let's discuss: How do you write your commits?

Let's discuss: How do you write your commits?

helderburato profile image Helder Burato Berto ・1 min read
Originally posted here

A subject that I always see in conversation circles with other developers is about ways to improve the writing of commit messages and how to make them more declarative so that other people can understand what happened in the course of the software development.

I always consult the following guides when I find myself in doubt:
https://chris.beams.io/posts/git-commit/
https://www.conventionalcommits.org/en/v1.0.0/

What format do you and your team use in your projects?

Ps: Remembering that it doesn't exist a right or wrong way, but choices that suit the needs of the team.

Discussion (6)

pic
Editor guide
Collapse
seds profile image
Ben Mezger (seds) • Edited

As of today, this is currently my git flow for most of my projects.

Commit messages

From: chris.beams.io/posts/git-commit/

  • Feat: Any code that contains only a new feature, whether a new model field, a new API flag, etc
  • Refactor: Any general code refactoring that does not contain anything new nor fixes anything.
  • Chore: Anything related to the build configuration, dependency updates
  • Docs: Anything related to documentation. This could be a function/class doc, READMEs, etc.
  • Fix: Anything that fixes a bug or any bad business logic

Don’t commit unrelated code, it’s easy for us to quickly change a function name and commit together with the new feature. Don’t do that. Separate your commits nicely, it will be much easier to revert commits, view logs and understand the development flow of a project.

Lower/upper case commits

I like things in capital, both the type and the commit message, but that's just my preference. Follow the project best pratices, if they use lower, stick with that.

Branches

Branches are temporary, but they do appear in a merge commit, so make sure the branch name makes sense.

Branch names are separated by what they bring to the code-base (fix, feat, refactor, etc). This make it easier to read logs, you know immediately from a merge commit that some feature that does X was merged.

Examples:

  • feat/create-read-syscall
  • fix/remove-bad-create-user-flag
  • refactor/move-syscalls-to-syscallsdir
  • chore/update-external-dependencies

Code tests

I’ve seen lots of repositories with test commits, where they usually bring a new test to some specific function. These are fine if you are adding a new test to something that existed long before, however, if you are writing a new function together with the test, make sure you commit both together. This allows us to revert a specific commit without having to revert twice in case the test is some commit after/before the feature.

Don’t:

5e2ac95 | * Fix: install dotenv on base not in dev, cause it is always used on app init
d0b041f | * Test: Add models tests
52b781d | * Feat: added version control models

Do:

5e2ac95 | * Fix: install dotenv on base not in dev, cause it is always used on app init
52b781d | * Feat: added version control models

I tend to indeed make test commit messages, however, before pushing the branch, I run a git rebase -i so I can fixup commits that should be together and reorganize the order of them.

Before a rebase:

cadf28c Test: Add question type tests [Ben Mezger]
b0a4537 Test: Add surveyadmin list test [Ben Mezger]
b0a40a7 Feat: Add institution to SurveyAdmin's list_filter [Ben Mezger]
bb0c7b0 Feat: Add question 'type' to SurveyAdmin's list_display [Ben Mezger]
842133a Feat: Enable list_filter for SurveyQuestionAdmin [Ben Mezger]
849823a Test: Add list filter tests [Ben Mezger]
cadf28c Feat: Add list_filter for user admin [Ben Mezger]
bd12b9c Fix: Migrate question type to survey response [Ben Mezger]

After a rebase:

b0a40a7 Feat: Add institution to SurveyAdmin's list_filter [Ben Mezger]
bb0c7b0 Feat: add question 'type' to SurveyAdmin's list_display [Ben Mezger]
849823a Feat: Enable list_filter for SurveyQuestionAdmin [Ben Mezger]
cadf28c Feat: Add list_filter for user admin [Ben Mezger]
bd12b9c Fix: Migrate question type to survey response [Ben Mezger]



Merges

Merging outside a service like Github? Then make sure you use git merge --no-ff instead of a git merge. This will prevent git from executing a fast-foward.

Keep it clean, stupid

Make sure you logs are readable. Having bad logs is the same as not having logs at all. Make sure you keep a readable history for yourself and others. Debugging bad commits will be much easier when running git bisect and your coworkers will thank you.

Collapse
helderburato profile image
Helder Burato Berto Author

Thanks for your reply, it's an amazing guide! 🚀

Collapse
andrematias profile image
André Matias

Hi.
I've used conventional commits pattern ultimatelly and it's working well.
I have some privated projects but all of them are only me writing code.
My doubts is always if I wait for a big commit or do it in small peaces.
What are you do?

Collapse
helderburato profile image
Helder Burato Berto Author

Thanks for the reply!
I try to follow the small commits approach and set the specific files involved in the commit message to have a track about the subject.

Collapse
jingxue profile image
Jing Xue

This. It's impossible to write a good commit message if you are committing 273 changes accumulated over a week. Always organize your commits into small self-contained units to begin with. Only then would you be able to write precise and concise commit messages.

Thread Thread
helderburato profile image
Helder Burato Berto Author

I totally agree with you.
When we start to break in smaller pieces it starts to make more sense the commit messages in intersection of files staged.