DEV Community

Malte Riechmann for visuellverstehen

Posted on • Updated on • Originally published at happy-coding.visuellverstehen.de

New git guidelines: We have switched to Conventional Commits

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

Top comments (33)

Collapse
 
grantdotdev profile image
Grant Riordan

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.

Collapse
 
schollii profile image
schollii

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.

Collapse
 
grantdotdev profile image
Grant Riordan

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.

Thread Thread
 
malteriechmann profile image
Malte Riechmann

I agree.

Thread Thread
 
schollii profile image
schollii

Fair enough

Thread Thread
 
shalerwells profile image
shalerwells

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

Collapse
 
ssustrich profile image
Shawn Sustrich

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.

Collapse
 
jmfayard profile image
Jean-Michel 🕵🏻‍♂️ Fayard • 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

Collapse
 
igoro00 profile image
Igor Ordecha

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.

Thread Thread
 
jmfayard profile image
Jean-Michel 🕵🏻‍♂️ Fayard • 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.

Collapse
 
fourofspades profile image
Four Of Spades

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.

Collapse
 
grantdotdev profile image
Grant Riordan

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.

Thread Thread
 
tamusjroyce profile image
tamusjroyce

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.

Collapse
 
malteriechmann profile image
Malte Riechmann • Edited

Thanks for your thoughts.

I see a short-term benefit of referencing an issue in the commit message. But I agree, in the long run, those possibly do not work anymore.

Collapse
 
cgatian profile image
Chaz Gatian

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

Collapse
 
franklinjavier profile image
Franklin Javier 🚀

Great tips.

Since GitHub has Draft Pull Request, you don’t need use “wip” keyword in the commit message.

Collapse
 
malteriechmann profile image
Malte Riechmann

Thanks for commenting :)

Yeah, GitHub and GitLab both provide draft pull requests/merge requests, but not all of our products use those.

Nevertheless, I also think WIP commits can most often be avoided.

Collapse
 
franklinjavier profile image
Franklin Javier 🚀

Agree with you 🤘

Collapse
 
anumber8 profile image
anumber8

Agree, i share the opinion that we should commit only complete work.

Collapse
 
langemeijer profile image
Casper Langemeijer

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.

Collapse
 
malteriechmann profile image
Malte Riechmann • 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.

Collapse
 
donnyroufs profile image
donny roufs • 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
Enter fullscreen mode Exit fullscreen mode
Collapse
 
malteriechmann profile image
Malte Riechmann

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.

Collapse
 
tamusjroyce profile image
tamusjroyce

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?

Collapse
 
malteriechmann profile image
Malte Riechmann • Edited

Yes.

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

Image description

Collapse
 
qoomon profile image
Bengt Brodersen

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

Collapse
 
malteriechmann profile image
Malte Riechmann

Thanks for sharing.

Collapse
 
mmasmoudi profile image
Mohamed Masmoudi

Thank you for sharing this Malte !

Collapse
 
malteriechmann profile image
Malte Riechmann

Always glad to help, Mohamed.

Collapse
 
anumber8 profile image
anumber8

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

Collapse
 
malteriechmann profile image
Malte Riechmann

Glad to help.

Collapse
 
airtonix profile image
Zenobius Jiricek • 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.

Collapse
 
ashleytayles profile image
Ashley Tayles

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.