Design decisions are not the "why"s. Commits are point in time checkpoints why development took a certain path. Let's take an example.
If a what looks like this: Store user full name in session table
The why can look something like this:
The full name is authoritatively stored in the user database and should be looked in using the user name. However, during deploys of the Raticate system, the cache gets invalidated and we need to quickly refresh it. This leads to a thundering herd system, as in incident 5244. By caching the full name in the session table we sidestep this problem entirely.
The reason why the Redis cache was not chosen for this data is because the session object is handed to the checkout system for processing, which can for security reasons, as described in document 7745, not access Redis.
When you find a bug later on related to a specific commit, the "why" in the commit can help explain the "what" that resulted in a bug.
It's all in addition to the changelog and other documentation if following a defined release methodology.
Personally I like having the "why" in a comment (with a pointer to the bug tracker item) if adding code. That doesn't work as well when deleting code, and for that, the commit message works as well as anything else.
That's one way but it requires a lot of discipline, and even then you'd have to manually go thru them to fish any "commit A introduced something, commit Z reverted that 40 commits after coz reasons" out of it.
From my experience people rarely read the commit message s, so it is better to put the why part into comments in the code, not git history. I mostly write the detailed why part in the commit only for refactoring changes.
My experience is that many changes span several blocks of code in a repo, so there's not always one single location to put the comment. There's also a blessing in that git commits don't need to be maintained like comments. Comments can drift if not maintained. A commit is only observed in-context.
Most developers seem to be poor "commit historians" by default, I'll admit. If you have the energy and consistency to enforce good history, it eventually becomes self-sustaining.
Why write meaningful commit messages at all then? Should we perhaps “git commit -m foo” all the time and call it a day?
My experience here varies wildly; I’ve worked on projects where commit history was carefully maintained and documented, as well as on projects with random squashing or random commit messages. Both had their own benefits and came with a cost too.
For larger, more complex or more mature projects, going through git history can be a common task. So here I’d prefer meaningful commit messages; git blame/bisect/etc gets easier, and sometimes any additional piece of docs has immense value. For smaller, simpler projects or prototypes, where history isn’t used that often, I don’t care that much.
Not proud of it, but honestly > 50% of my commit messages are "wip" or similar.
Source backup is one of my primary uses for SCC, and when I step out for lunch, or need to knock off for the day, I commit where I am, and push with a "wip" (work in progress) message.
The feature branch name I merge is probably the most useful. It's an aggregate of all my commits and what I'm working on.
I do this too, but when I come back from lunch I git reset HEAD~1 and keep going till I have a meaningful piece of work to commit on its own. You can also use interactive rebase to reorder or squash commits if you realize that for readability reasons it makes more sense for a refactoring you started later to appear earlier in the stack or for a subpar commit and its subsequent fixup to be combined. This makes the final history more easy to read for reviewers, and (after it's merged) more easy to read for future you and other devs on the project too.
interactive rebase is (IMHO) the golden ticket for this. Unfortunately, if you're using git as a backup then that means you pushed the commits, so a `git push -f` will be required. I do that all the time and think in general we are unnecessarily scared of it. As long as you're the only person working on the branch, a push -f is NBD. Never do it to master though or a shared branch unless you plan to bring donuts or something in later as an apology.
Yeah where I work, we strongly encourage interactive rebase on solo feature branches.
In fact, even the hairiest long-lived branches can get cherry-picked apart into several "layers" of branches to get reviewed and merged piecemeal. It's really easy if you're starting from too many commits. It gets harder (not impossible) if individual commits commingle said layers.
The commit message is also for future me. Future me doesn't remember what today me can easily recall about the last week of debugging and reverse engineering about how the system works. A thorough commit message can really help when trying to figure out bisect bugs point to a particular commit or to better understand individual lines of code when reviewing code with git blame.
If I'm adding something weird and funky that requires a long explanation of context, it goes in a comment (or even an ADR). If I'm removing it, it goes in the commit message.
Well, there's one particular exception that I find super relevant -- my own commit messages. There are a number of times when I know I made a code change, and can't remember why, and my own commit messages in the git log remind me.
Hopefully as a side benefit others also find them helpful, but my present self is always grateful to past-self's conscientiousness!
The main reason i read commit messages, is when i change some code i want to know why it was introduced in the first place to ensure i am not regressing some feature. The why is important, even if its just to know that there is no big story.
From my experience, people rarely write meaningful commit messages or comments in code, and they expect you to just glean everything you need to know by simply reading the code itself.
Out of three (commits, comments, docs), the commits are least approachable, just few changes in the code will erase original commit in the blame.
By all means write good commit messages, but crystallize the info in them into changelog or other docs every bigger release