Hacker News Reader

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)

View on HN

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.

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.

Reply on news.ycombinator.com