Malte Riechmann for visuellverstehen

Posted on Oct 22, 2022 • Updated on Oct 24, 2022 • Originally published at happy-coding.visuellverstehen.de

New git guidelines: We have switched to Conventional Commits

#git #webdev #programming #opensource

Giving teams as much autonomy as possible is a good idea, but having some company-wide guidelines can also help. Those guidelines will help you when people switch teams, work on multiple products, or train new colleagues.

Discuss, decide, repeat

We recently discussed some technology-related topics with all software developers at visuellverstehen. One of the outcomes of this discussion is new git guidelines. After a short debate, we have officially switched to Conventional Commits.

It is fun to see all the latest commits following a new syntax. I am curious about what we will say about this change in six or twelve months. For sure we will discuss and decide again – for the better.

New git guidelines

Below you can find the November 2022 edition of our git guidelines.

Repositories

Repositories should be named like this: vvcode-name_of_project

Branches

The main branch should be named main
The people working on a product decide if they want to work with further branches
If you need further branches, it is advisable, to add the number of the issue and a short title inside of a branch name, e. g.:
- 100-validation-errors
- 101-basic-search
- 102-german-translation
- 103-live-deployment
- 104-url-formatting

Commits

We use the syntax from Conventional Commits
Commit messages include one of the following prefixes:
- fix: to fix bugs
- feat: to introduce new features
- chore: to make general changes
- ci: to work on continuous integration/continuous deployment
- refactor: to improve existing source code
Commit messages should be written in the present form
Commit messages should be written in English
Commit messages should start with a lowercase character
It is advisable to add the issue number to a commit message
Practical examples of commit messages:
- fix: display validation errors properly, refs #100
- feat: implement basic search, refs #101
- chore: add correct german translation, refs #102
- ci: repair live deployment, refs #103
- refactor: unify URL formatting, refs #104
If a commit is a work in progress, it should be marked as such:
- fix: display validation errors properly (WIP), refs #100
- feat: implement basic search (WIP), refs #101
- chore: add correct german translation (WIP), refs #102
- ci: repair live deployment (WIP), refs #103
- refactor: unify URL formatting (WIP), refs #104

Latest comments (33)

Ashley Tayles • Dec 20 '22

I would say no to ticket references. I always open a GitHub issue with details of that said source ticket in, but not just the ticket number. A migration from an old in-house solution to ServiceNow made many of our legacy commit comments completely useless when trying to understand why a bit of code was added.

Zenobius Jiricek • Dec 19 '22 • Edited

Why are you advising?

Just enforce it with automation.

Prs get rejected if the branch didn't match a format.

Pr titles get auto formatted.

Only allow Squash merge to master.

Only allow "pr title as squash merge commit"

Auto write a comment with the ticket so it links to JIRA.

Force delete branch on merge.

Like... None of this should be optional and you don't need inconsistency in team projects it just makes context switching harder than it needs to be.

Casper Langemeijer • Oct 25 '22

We've moved away from something like SemVer on which Conventional Commits is based a long time ago. I know Conventional Commits is all the rage these days, but I'm telling you: You're doing it wrong.

In my opinion, a commit message should not say what has changed. Because what has changed is in the commit itself. No, the commit message should say why this change was made. Because a client (what client?) asked, because a bug was fixed (reference to issue tracker), because a partial refactor was deemed beneficial (why, what ultimate goal) or because an discussion among colleagues (the arguments matter) led to this change.

Because the only time your commit message is ever read, it is when your future self is doing a git blame to find out why you made this idiot change to something that seemed to work before.

Said differently: A commit message is the apology to your future self.

The changelog does not need to be composed of commit messages. Having machine-readable commit messages to compose something of a changelog is an awfully bad idea. This is because the changelog of commit messages cannot be changed independently. If for example you made a typo in the message, or if you forgot to add an entry to the message there is a problem. The correct thing to do is rebase-and-fix the commit, but that is not feasible for big projects with many merges. Also, rebases and force-pushes will probably break your release automation anyway.

Instead, make add the machine-readable changelog as a file in your project, adding the entries as you go along. Or just write a human-readable changelog in your project. Make your users a first priority instead of automating there needs away.

To automate releases, tags are the way. For rolling-release continuous delivery projects branches are the way.

Btw: I'm not saying 'sales says ship it!' is a valid commit message.

Malte Riechmann • Oct 26 '22 • Edited

Thanks for reading and sharing your opinion on this. I do not agree to all of your statements, though.

The changelog does not need to be composed of commit messages

I agree. We do not use Conventional Commits to create a changelog. We use the syntax of Conventional Commits and some additional guidelines, to create unified and readable commit messages.

Because the only time your commit message is ever read, it is when your future self is doing a git blame to find out why you made this idiot change to something that seemed to work before.

I do not agree. This is simply not true. I read commit messages all the time for a lot of different reasons.

Make your users a first priority instead of automating there needs away

Yes. I agree.

You're doing it wrong.

I do not agree. I think there are always multiple solutions and different approaches. I think we are doing it different, not wrong.

Have a nice day.

tamusjroyce • Oct 25 '22

How does this work with Jira and other story based agile boards that read commit history?

Jira will automatically comment about commits that relate to story # within the story.

Github and gitlab with issue/features submitted too?

Malte Riechmann • Oct 25 '22 • Edited

Yes.

Check out this example of an issue referencing commits in GitLab:

Mohamed Masmoudi • Oct 25 '22

Thank you for sharing this Malte !

Malte Riechmann • Oct 25 '22

Always glad to help, Mohamed.

Bengt Brodersen • Oct 24 '22

Feel free to have a look at my cli util to ensure commit convention github.com/qoomon/git-conventional...

Malte Riechmann • Oct 24 '22

Thanks for sharing.

donny roufs • Oct 23 '22 • Edited

IIRC ticket numbers are generally placed in the footer (e.g. after the body of a commit) so like:

feat: show posts

So that users can see their posts...

Ref: #123

Malte Riechmann • Oct 24 '22

Thanks for pointing it out.

You are right. That is the official way, but we reference issues directly in the first line of a commit message.

anumber8 • Oct 23 '22

Thanks for sharing the approach, looks very interesting and helpful.

Malte Riechmann • Oct 24 '22

Glad to help.

Grant Riordan • Oct 23 '22

I often have this discussion of wether a commit message should include the ticket number or not.

In my opinion Ticket numbers are superfluous really. They're only useful if you endeavour to utilise the same Ticketing system for the life of the product (which realistically isn't always viable).

More importantly I believe you should write useful and meaningful commit messages without relying on the ticket as reference. Too many times I've seen people write very poor commit messages all because they feel that the ticket number is sufficient information. However, changing the ticketing system means all context of requested / completed work tied to the ticket + commit, could be potentially lost.

Shawn Sustrich • Feb 13 '23

I think it's important that you have a way to tie commits to a ticket. Ive been on project where pre commit hooks in git verified that all check-ins were for open tickets. It's easy enough to just slap a bug-1234 at the top and even easier to ignore them if you don't want to see them. You could mput the commit hashes in ticket but I think more often it's more important on the code side to track what commits are for what bug versus what looking at a ticket to see the commits. I'm thinking for code reviews etc. If yes poor commit messages are an issue, but that's an issue that exists independent of anything else.

Chaz Gatian • Jan 23 '23

Tickets help enormously because PMs don't add information to the commit message. How do you ever determine what customer requested a specific feature?

Jean-Michel 🕵🏻‍♂️ Fayard • Oct 27 '22 • Edited

People are not wrong, they should have a different context then you have.

For example we work with the pull request as being the unit of work. When a PR is done,v we squash and merge .So I count l couldn't care less about the the commit message of individual commits.

At the end of the day, git is not our master, it's just a tool

Igor Ordecha • Oct 28 '22

Yup. I think this workflow is quite good:

I look at an issue
I create a branch(name doesn't matter)
After one commit I create a draft PR(the description has # of the issue)
when I commit to that branch(and PR) all the tests automatically run and maybe even a preview is deployed. This incentives me not to get lazy and actually commit every change. The names of my commits are not really relevant. It obviously can't be "a", "aa", "b", "1234" but it doesn't have to super precise and specific.
when I think I'm done I change the draft PR to a regular PR. Here's where my responsibilities end.
someone reviews it and changes the name of the PR if I didn't get it right
if it's all good, squashes it and pushes to main.
GitHub automatically sets the commit message to (<# of the PR>) so because the maintainer changed the PR name earlier it's just pressing commit.

Inb4 I haven't worked at a corp with a big dev team. I worked on very small commercial projects and I contributed to fairly large open source projects and it worked there but I can't see why this wouldn't work in a big company.

Jean-Michel 🕵🏻‍♂️ Fayard • Oct 28 '22 • Edited

Sounds good to me.

One thing to have in mind is that git and therefore its supposed "best practices" were developed with a very special kind of projects in mind: bazaar-like open source projects with loads of contributors. Most notably Linus Torvalds's own Linux Kernel project.

If that's what your project looks like, do respect the best practices. If note, feel free to drop the ones that doesn't improve your developer life.

The Cathedral and the Bazaar: Musings on Linux and Open Source by an Accidental Revolutionary is an essay, and later a book, by Eric S. Raymond on software engineering methods, based on his observations of the Linux kernel development process and his experiences managing an open source project, fetchmail. It examines the struggle between top-down and bottom-up design. The essay was first presented by the author at the Linux Kongress on May 27, 1997 in Würzburg (Germany) and was published as the second chapter of the same‑titled book in 1999.

schollii • Oct 26 '22

Grant I agree there is a problem there (too short git messages) but I have to disagree on the solution (don't include ticket # so people can't be lazy). For one thing once the feature branch is merged and the branch name deleted, there is no longer a way of knowing what ticket a particular commit belongs to.

This has been very useful in the past when searching through commits. And not deleting branches is not practical, leads to an absolute mess of branches.

On my teams we agree that the commit message should be detailed enough to understand what changed, and that the why can be obtained from the ticket itself.

And on the unlikely event that the ticketing system changes, I'm my experience that is so rare that it is not worth worrying about.

There will be many other complications to deal with, such as maintaining change history at all vs starting clean.

Also, I would be very surprised if in such situation, the team or IT were not open to allowing view only access to the old system for a while, like 6 months or a year. Beyond that, no one cares much about preserving history of tickets or commits.

Grant Riordan • Oct 26 '22

That's a good point, yes. Agree in some cases ticket numbers are useful. I think I didn't explain myself correctly, as I was more trying to make the point of Yes , 2e should write descriptive messages and not rely solely on ticket numbers as some do.

Malte Riechmann • Oct 26 '22

I agree.

schollii • Oct 26 '22

Fair enough

shalerwells • Oct 29 '22

The ticket numbers are good for automation. Let hooks do their thing and you can avoid dealing with Jira.

Four Of Spades • Oct 24 '22

Assuming you have never worked on a large project with multiple simultaneous releases or as a release manager. Being able to tie customer issues to source code changes is critical.

Grant Riordan • Oct 24 '22

But if we're talking about releases, you would tag your releases , and log the issues fixed and such on your change log. Still don't see a necessity for ticket numbers within commit messages or branch names.

tamusjroyce • Oct 25 '22

I agree with it being important to add ticket and story # to your commits. Issue trackers and stories on story boards should be able to consume those commit messages and tag them to the problem.

If you switch ticketing or story boards, migrates tickets and stories should migrate the linked commits too.

If you don’t have a system that consumes the #, you either have a small project. Or tech debt.