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-errors101-basic-search102-german-translation103-live-deployment104-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 #100feat: implement basic search, refs #101chore: add correct german translation, refs #102ci: repair live deployment, refs #103refactor: 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 #100feat: implement basic search (WIP), refs #101chore: add correct german translation (WIP), refs #102ci: repair live deployment (WIP), refs #103refactor: unify URL formatting (WIP), refs #104
Top comments (33)
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.
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.
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.
I agree.
Fair enough
The ticket numbers are good for automation. Let hooks do their thing and you can avoid dealing with Jira.
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.
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
Yup. I think this workflow is quite good:
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.
Sounds good to me.
One thing to have in mind is that
gitand 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.
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.
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.
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.
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.
Tickets help enormously because PMs don't add information to the commit message. How do you ever determine what customer requested a specific feature?
Great tips.
Since GitHub has Draft Pull Request, you don’t need use “wip” keyword in the commit message.
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.
Agree with you 🤘
Agree, i share the opinion that we should commit only complete work.
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.
Thanks for reading and sharing your opinion on this. I do not agree to all of your statements, though.
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.
I do not agree. This is simply not true. I read commit messages all the time for a lot of different reasons.
Yes. I agree.
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.
IIRC ticket numbers are generally placed in the footer (e.g. after the body of a commit) so like:
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.
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?
Yes.
Check out this example of an issue referencing commits in GitLab:
Feel free to have a look at my cli util to ensure commit convention github.com/qoomon/git-conventional...
Thanks for sharing.
Thank you for sharing this Malte !
Always glad to help, Mohamed.
Thanks for sharing the approach, looks very interesting and helpful.
Glad to help.
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.
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.