[ilyt]

Design decisions should really go into docs rather than commits.

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

[xorcist]

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.

[ilyt]

And why that should not be in the docs or comments but in some random commit that people will only read when it shows up in git blame ?

[Espressosaurus]

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.

[zeroonetwothree]

It’s much easier to find the commit that added a piece of code than the doc

[midoridensha]

If the doc is on Confluence, you'll probably never find it.

[GuB-42]

In some workflows, commit messages in the release branch are the changelog. It usually involves squashing or merge commits.

[ilyt]

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.