[rollcat]

Depends. Sometimes a one-liner or a reference to a ticket is enough.

There are times when I make a one-line change and write a paragraph or two explaining why it had to be done. But these kinds of things often drown in the noise of a dozen other changes. If that one was important enough, I will reference it in an ongoing discussion or documentation, or at least include "read below:" on the first line.

I usually see people include a more elaborate commentary with the pull request. If the changeset is good but the series of individual commits is a bit messy, just merge by squashing.

(Also: this comment is meta.)

[Cthulhu_]

A one-liner: sure. A ticket? No; ticket systems are transient and not always available. You shouldn't need to open an external system that may no longer exist in 20 years time (for example) to get the full context.

Compare the Linux commit history, every commit has its full context and explanation and they do not rely on external systems.

[yaris]

Our ticket system survived almost 20 years and is useless anyway, because approximately half of the history consists of pairs like: commit 12345 ”fixed a bug, see ticket 54321” - ticket 54321 ”fixed by commit 12345”.

[dirkf]

20? Try 5...

I"m working on a repository that uses at least four different jira ticket number formats. All commits should have a jira reference but I think only the current format can still be looked up. And maybe the predecessor if you know what jira field to query. All the rest are lost in corporate limbo. Not that those tickets added much more context to the actual commit...

So yeah, always write your commit messages as standalone as possible.

[drac89]

I agree maybe not adding the ticket link is better if you know that the system might not be available in the future.

You can not avoid it all the time but maybe It's better to use the PR description for that purpose.

[pydry]

If I feel the need to write a paragraph in a commit message it's usually a sign that Im writing prose that belongs in actual docs.

Commit messages are a great place to bury docs nobody will look at.