Very though out set of guidelines, thank for this. As I learn more optimized workflows and git usage solely through terminal these days I have come to the realizations that even the tips mentioned here seem obvious and considered good practice among many professionals they arent necessarily used by majority. So I do believe all of this is subjective to an extent because using git as objective means to accomplish version control and just that. I personally like conventional commits and have for years because of its simplicity. Keywords such as feat, fix, build, and docs tell me already what I need to know when searching history or how to version next release.
I've noticed that I split commits and make very verbose but clear messages for each commit, only to never use this afterwards.
Meanwhile my coworkers just commit with "lol" and get the same result. What I learned from this is that you don't need to split commits, just commit everything at once and add a "good enough" message. E.g. if you're working on a provider just use "Updated provider"
You migrate relevant parts of that diff into your workdir, test and commit.
Is it that hard? What is this question even? Do you lose consciousness and project awareness in these cases? Why someone must split all the work before it's needed, when it's only needed in 0.01% of all cases? Why wouldn't you do this job when the need to rollback arises? Good arguments for commit granularity exist, but this one makes little sense, like many others.
I've never worked on a team that had conventions for both commits and PRs. In general, the goal of such things is to help trace work across multiple systems, and for future research trying to track down old changes. All the places I've worked or consulted, they do that at the PR level, not the commit level. So PRs will start with a ticket #, commits are freeform.
That being said, some places do have commit standards. Just ask the team what they do when you start somewhere. Don't bring conventions in where a team doesn't use them - it just adds noise. If you or the team see how adding conventions can benefit your work, talk about it and make a decision together.
Good thing Microsoft has never been evil. Otherwise, one might be concerned about locking up your project's history in Github's/Microsoft's proprietary issue tracker (embrace, extend, extinguish!) rather than open source tools like Git that you can migrate out of.
Oh gosh yes, that sure would be dangerous to lock everything into Github. I've never worked on a team that did so, though. To be honest, I've never used Github's issue tracker at all. Seeing as PRs are also commits when they merge, PR-level tracking migrates just fine to any other system you'd like.
My advice is never use conventions for personal/solo projects - they do not matter.
When it comes to working in teams I actually do recommend them because during a code review you can - at a glance - read what each commit has done so you can familiarise yourself with the steps the developer took to reach the state in the PR.
For small teams I'm a big proponent of slimmed down version of Conventional Commits' standard. At our startup we would only really use these types: fix/feat/chore/docs/refactor/revert/ci/test.
Something simple like:
fix(ControlPanel): popover animation no longer causes layout shifts
Depends on the size of the project. Some informal convention can be pretty helpful when a personal projects gets sufficiently large, to the point where you may at some point have to look at the git log.
Yes you are right, well said! I suppose it's key to look at your project from a birds' eye view and try and estimate how large scale you expect it to be.
If you're building the next open source self-hosted facebook, yeah I think a convention is necessary. However, if you're building "my calculator app in Rust" then you're probably okay just doing commits "abcd123" just so that you can have remote code storage :^)
Doesn't matter much. What works for me is it's easily skimmable. Rather than say "fix the command widget", it's better to say "command widget fixed". Because if you do verbs, most of your commits will start with "fixed" and stuff and won't be helpful when people actually try to read it.
Some people do require to do the whole fix:, chore:, docs:, refactor:, but I find this is more as some quality control tool rather than a documentation tool.
Ours is integrated heavily with Jira, so using the ticket number helps the most. We're likely to find commits/PRs from tickets, or jump to the ticket for the context of the commit. The other entry point is looking at git blame on an IDE, especially a funky looking line of code like `if (nonsense logic)` is causing a bug regression. When this happens, I want the ticket. I can immediately just paste the ticket number into Jira.
As always, different styles are suited to different cultures. Read everything here for ideas, but pick one that fits your culture the best.
The only "convention" that exists is the Conventional Commits' one. It is sensible and compatible with some tools. As long as you write "fix:", "feat:" or "chore:" you'll be fine.
Don't overthink it though, it's a thing that is used in some open-source projects and companies. As long as you follow the rules of the project, you'll be fine. Same for the coding style and format, do like everyone else.
Half of it is automation to generate pretty changelogs if an audit ever happens. The other half is to make sure that devs know that rules are set in order to make them think about what they are doing. It seems a bit restrictive, but it's a good way to say "your commits should be clean and focused on one topic and one topic only."
For my projects I just use "Temp" and "Works". Sometimes a couple-words summary, which works as a temporary anchor for diffs. Never found myself reading through old commit messages to grasp something, in any vcs (used cvs, svn, git). If there's a necessity to find a commit, I just blame or log with files. But there's usually no necessity, cause I prefer to move forward rather than digging the past.
Before anyone screams, I don't expect you to browse my projects, even when they are public or shared. Writing this because it's one of the practical ways. I know you don't like it and would fire me asap even for my project commits, yeah dream about it.
My company has a terrible commit message culture. Half of the commits begin with "in which our hero..." - you can imagine how insanely irritating it is to find relevant changes in logs...
line 1: short description. fit on 1 line. put effort into making it as short as possible while still giving the gist of what was done. maybe a github/lab issue #.
line 2: blank
line 3+: long description, paragraphs, details, context for decisions made, rambling
I've written mine up as I've noticed I was repeating myself a bit once my opinions stabilized.
See https://jiby.tech/post/my-git-worfklow/
> Use the imperative mood in the subject line
I like to think of this not as giving an order to the codebase, but as casting a spell.
Very though out set of guidelines, thank for this. As I learn more optimized workflows and git usage solely through terminal these days I have come to the realizations that even the tips mentioned here seem obvious and considered good practice among many professionals they arent necessarily used by majority. So I do believe all of this is subjective to an extent because using git as objective means to accomplish version control and just that. I personally like conventional commits and have for years because of its simplicity. Keywords such as feat, fix, build, and docs tell me already what I need to know when searching history or how to version next release.
Great read!
I've noticed that I split commits and make very verbose but clear messages for each commit, only to never use this afterwards.
Meanwhile my coworkers just commit with "lol" and get the same result. What I learned from this is that you don't need to split commits, just commit everything at once and add a "good enough" message. E.g. if you're working on a provider just use "Updated provider"
What kind of stupid advice is that?
How do you want to roll back a change of a specific feature if multiple works are committed at once.
You migrate relevant parts of that diff into your workdir, test and commit.
Is it that hard? What is this question even? Do you lose consciousness and project awareness in these cases? Why someone must split all the work before it's needed, when it's only needed in 0.01% of all cases? Why wouldn't you do this job when the need to rollback arises? Good arguments for commit granularity exist, but this one makes little sense, like many others.
Everything at once is presumable a unit of work you can roll back.
I hope that is what they mean!
I've never worked on a team that had conventions for both commits and PRs. In general, the goal of such things is to help trace work across multiple systems, and for future research trying to track down old changes. All the places I've worked or consulted, they do that at the PR level, not the commit level. So PRs will start with a ticket #, commits are freeform.
That being said, some places do have commit standards. Just ask the team what they do when you start somewhere. Don't bring conventions in where a team doesn't use them - it just adds noise. If you or the team see how adding conventions can benefit your work, talk about it and make a decision together.
Good thing Microsoft has never been evil. Otherwise, one might be concerned about locking up your project's history in Github's/Microsoft's proprietary issue tracker (embrace, extend, extinguish!) rather than open source tools like Git that you can migrate out of.
Oh gosh yes, that sure would be dangerous to lock everything into Github. I've never worked on a team that did so, though. To be honest, I've never used Github's issue tracker at all. Seeing as PRs are also commits when they merge, PR-level tracking migrates just fine to any other system you'd like.
Why not just use the commit message then? What benefits do you get from building your workflow around the proprietary PR interface?
Comments, reviews, screenshots, etc etc?
My advice is never use conventions for personal/solo projects - they do not matter.
When it comes to working in teams I actually do recommend them because during a code review you can - at a glance - read what each commit has done so you can familiarise yourself with the steps the developer took to reach the state in the PR.
For small teams I'm a big proponent of slimmed down version of Conventional Commits' standard. At our startup we would only really use these types: fix/feat/chore/docs/refactor/revert/ci/test.
Something simple like:
fix(ControlPanel): popover animation no longer causes layout shifts
is perfect
Depends on the size of the project. Some informal convention can be pretty helpful when a personal projects gets sufficiently large, to the point where you may at some point have to look at the git log.
Yes you are right, well said! I suppose it's key to look at your project from a birds' eye view and try and estimate how large scale you expect it to be.
If you're building the next open source self-hosted facebook, yeah I think a convention is necessary. However, if you're building "my calculator app in Rust" then you're probably okay just doing commits "abcd123" just so that you can have remote code storage :^)
Thanks a lot!
Doesn't matter much. What works for me is it's easily skimmable. Rather than say "fix the command widget", it's better to say "command widget fixed". Because if you do verbs, most of your commits will start with "fixed" and stuff and won't be helpful when people actually try to read it.
Some people do require to do the whole fix:, chore:, docs:, refactor:, but I find this is more as some quality control tool rather than a documentation tool.
Ours is integrated heavily with Jira, so using the ticket number helps the most. We're likely to find commits/PRs from tickets, or jump to the ticket for the context of the commit. The other entry point is looking at git blame on an IDE, especially a funky looking line of code like `if (nonsense logic)` is causing a bug regression. When this happens, I want the ticket. I can immediately just paste the ticket number into Jira.
As always, different styles are suited to different cultures. Read everything here for ideas, but pick one that fits your culture the best.
The only "convention" that exists is the Conventional Commits' one. It is sensible and compatible with some tools. As long as you write "fix:", "feat:" or "chore:" you'll be fine.
Don't overthink it though, it's a thing that is used in some open-source projects and companies. As long as you follow the rules of the project, you'll be fine. Same for the coding style and format, do like everyone else.
So only point of this is for automation?
Half of it is automation to generate pretty changelogs if an audit ever happens. The other half is to make sure that devs know that rules are set in order to make them think about what they are doing. It seems a bit restrictive, but it's a good way to say "your commits should be clean and focused on one topic and one topic only."
For my projects I just use "Temp" and "Works". Sometimes a couple-words summary, which works as a temporary anchor for diffs. Never found myself reading through old commit messages to grasp something, in any vcs (used cvs, svn, git). If there's a necessity to find a commit, I just blame or log with files. But there's usually no necessity, cause I prefer to move forward rather than digging the past.
Before anyone screams, I don't expect you to browse my projects, even when they are public or shared. Writing this because it's one of the practical ways. I know you don't like it and would fire me asap even for my project commits, yeah dream about it.
The official documentation contains some guidelines and the reasoning behind them:
https://git-scm.com/book/ms/v2/Distributed-Git-Contributing-...
https://git-scm.com/docs/SubmittingPatches#describe-changes
For examples of projects that do this very well, I usually point people to the Linux kernel (for which Git was invented) and Go.
https://www.kernel.org/doc/html/latest/process/submitting-pa...
https://go.dev/doc/contribute#commit_messages
On some hobby projects I just do a "git add ./*" and set an exquisite commit message along the lines of
At work, and when I push some OSS code, I do as the Romans do.You dont need /*
git commit -a -m "ugh, syntax"
My company has a terrible commit message culture. Half of the commits begin with "in which our hero..." - you can imagine how insanely irritating it is to find relevant changes in logs...
Is that like some story agile thing like "as a bored user who wants to close the dialog I want to close the dialog"
For branch commits, anything (no profanity lol!)
For merge commits <ticket number> - <simple description>
An "and" or long description hints it needs to be broke up
I usually use the one we use in the FreeBSD project, which is to have the subject be of the form "component: action".
Start with a verb in imperative mode, first letter uppercase, no punctuation at the end, for example: “Add about page”.
To me it depends on your goals:
Do you want to use it to power versioning and CI?
Do you want commits traceable to tickets/issues
Do you want to do merge commits or squashes?
Do you want to generate change logs from the commits?
Different strategies will benefit different needs.
I put the ticket number first, that way I always know which commits are mine if I do a rebase. I don't know why everyone doesn't do this.
I describe in past tense what I just did.
For example -
" uuid added to the test to make the newly created mailbox different each time "
line 1: short description. fit on 1 line. put effort into making it as short as possible while still giving the gist of what was done. maybe a github/lab issue #.
line 2: blank
line 3+: long description, paragraphs, details, context for decisions made, rambling
applicable for feature or bugfix:
1. describe how things work (or not work) currently
2. proposed solution to the problem this commit attempts
3. more implementation/technical details
4. (optionally) tests or reproduction scenario
For juniors, whatever gets you yelled at less. For seniors, whatever you wouldn't yell at. In any case there will be yelling.
Wisdom section
“Why” not “what”