Hacker News Reader

Comment by tengbretson | Hacker News Reader

I've actually found the opposite to be true. That usually the people harping for rich commit messages are the ones not thinking of others. That they are trying to get their coworkers to bend or produce extra work just to make their personal workflow more ergonomic. The information they seek is already redundantly documented, often 3 times over in the form of PR messages, jira tickets, requirements documents, slack history, etc.

View on HN

In a perfect world yes that is true, but I've worked at multiple places where Jira got reshuffled by someone and either entire projects got deleted or ticket ids were reset.

Slack history and requirement documents are rarely linked in commit messages and looking through thousands of documents and channels to search the context of a commit is nauseating.

There's never a need to write an essay in a commit message, but 2-3 paragraphs won't kill anybody either.

There are better uses of resources than to amortize the cost of a jira migration that may never even happen across all devs in perpetuity.

Jira always gets shut down before the repo. Often years before. For a thousand reasons. Take these two, for example: git is free, and jira is shit.

But are they at all discoverable from the code base? Those PR messages, jira tickets, and slack history ought to be linked to in the commit message, and that requirements document checked in.

(None of those links help when you switch to different providers; but that might not be too bad, depending on timescales of those changes)

Most teams I've been on just link to the PR from Jira and Slack. The PR links to the commit message, and the commit message explains the change.

Other stuff like "this is ready, can you review it?", or "we can ship feature X now" lives in the other tools.

Note that (in the rare case where you want to), you can then search for links to old PRs in the other tools. Also, putting the jira ticket number in the commit message usually makes sense.

anything that is not in the commit message or in the commit itself is practically useless. documentation covers how to use a thing. it usually doesn't cover why a change was made. that why also normally does not end up in code comments, and even less so would be aparent from the change it self. the commit message remains the only place where the why can be documented meaningfully and along with the change where it is needed.

at least in my current project working with legacy code that i am not familiar with, the why is the most important detail about a commit.

Reply on news.ycombinator.com