4 ms·

The real takeaway is that different projects have different requirements. In over 30 years of using source control, I've never once worked on something where i

The real takeaway is that different projects have different requirements. In over 30 years of using source control, I've never once worked on something where it's useful to include the component (article calls it scope) in the description in a standardised way. It's obvious what components are affected based on where in the source tree the affected files are. Similarly "bug", "fix" or "feature" adds no useful value. It's important or it wouldn't be checked in. The only thing I've found useful, and which the article doesn't even consider, is a link / id for the relevant change request. The commit already contains all the information about what was done in the change, what's missing is the context about why. Even on my solo projects I include a JIRA reference in square brackets before the description. If it's just something I randomly decided to fix during the course of development, I'll create a short 1 line JIRA to get an id and explain the why there.

literallyroy 4mo ago
Is the benefit of using a separate source that you can include images or something else I’m missing? Couldn’t you include context in the commit body?
SamuelAdams 4mo ago
It is useful if you automate generating release notes. Then your notes are grouped by new features first, then bug fixes after. This makes it a little easier for non-technical uses to read.
- pseudalopex 4mo ago
  Commit messages are good release notes rarely.
  - llimllib 4mo ago
    it's usually a "something is better than nothing" situation. If you have somebody willing to write custom release messages, that's definitely better; but conventional commits is better than nothing for it.
    - ralferoo 4mo ago
      Absolutely not. Commit messages should never be automatically passed through to the end-customer. I also worked in a place that tried it once and it was a disaster. Sure, a list of commit messages can be a useful start as a list of things that might want to be put in the release notes, but very rarely is the developer the right person to be explaining those changes to the end user. If a developer is being asked to do that, it's a good sign that the PM isn't doing their job properly.
    - pseudalopex 4mo ago
      They did not say generated release notes are useful if you care so little you would write no release notes without them however.
  - nkrisc 4mo ago
    You can have a writer re-write them into acceptable release notes. It gives them a good and accurate starting point.
    - pseudalopex 4mo ago
      Closed issues are a better starting point in my experience.
  - mystifyingpoi 4mo ago
    That's right, but with AI help + some hallucination you can get nice looking release notes out of the worst mess of commits.
adammarples 4mo ago
Pretty much everywhere I've worked recently enforces some kind of jira ticket number in the PR title
- procaryote 4mo ago
  Perhaps it's useful to ask why? What does the jira ticket give you that a longer PR message can't do better?
  - adammarples 4mo ago
    Saves you a click maybe, at least it's easy to always know what ticket you're working on right in the terminal
dualvariable 4mo ago
This is the way we did it when we used JIRA. For GH issues you can always navigate back to the PR discussion (which should have linked issues and other pointers in it) from the commit. Of course when we switched to GH issues, we largely abandoned JIRA and years later the instance got turned off and deleted. Now all those JIRA tags are entirely useless. IMO that actually argues for tight coupling between your issue tracker and your git repo. And what you really want is portability (which I don't see how you get other than with tight coupling). Ideally there would be open standardized formats, but as it is, github is the 800# gorilla that defines the format and as long as gitlab and other clones can slurp in github project metadata (or at least PRs) then that effectively gets you closer. But any way... Fixed, immutable pointers to an Atlassian product that you might not be using in 5 years is not a good policy. I'd sooner accept the policy that the git commits needed to stand entirely on their own and all the information about the "why" of the change needed to be baked into the git commit or the comments in the source (I think that fails, though, since everyone is overly terse in git commits and summarizes issues and loses information--and the back-and-forth dialog in a PR discussion is useful because it contains more than just one person's voice summarizing the reason for the change).
- mystifyingpoi 4mo ago
  > we largely abandoned JIRA and years later the instance got turned off and deleted Sorry to be nitpicky, but why did you abandon a tool that contained a lot of valuable knowledge? That's not the fault of GH nor JIRA, that's your fault. At least you'd back up descriptions + comments from these JIRA sources.
  - oskarpearson 4mo ago
    Like many tools defending their moats, tools like Jira don’t make it easy to get one’s data out.
    - ralferoo 4mo ago
      That isn't true though. It's very easy to export your data from JIRA. From your board, go to the List tab, filter the items to whatever you want, and then click ... and you can export the data in various different formats. Exporting as XML dumps everything.
chickensong 4mo ago
> Similarly "bug", "fix" or "feature" adds no useful value. If you're not using/tied to an issue tracker, embedding tags like these in git gives you some basic metrics.
eikenberry 4mo ago
> The only thing I've found useful, and which the article doesn't even consider, is a link / id for the relevant change request. The commit already contains all the information about what was done in the change, what's missing is the context about why. The "why" is THE thing that needs to go in the git commit message. Capturing "why" is the entire point of that message and slapping a link to some external (and eventually absent) resource is not a good substitute.
- mmcnl 4mo ago
  It is a good substitute. 1. Usually the commit message is often too short to capture the "why" adequately. 2. It is very beneficial to capture the why in one single source of truth, and that usually is not the Git commit message in a business context. Hate on Jira all you want, but if you capture the "why" there, you can add comments, view history, add rich context, link dependencies, add rich context, etc. Can't do that in a Git commit message.
  - jsve 4mo ago
    You can put that in the body of the commit message, not everything has to go in the subject line.
  - eikenberry 4mo ago
    My ire is more directed at github PRs than Jira... but the same basic idea applies. You want a single source of truth and you want that as close to the origin (the code) as possible. Your history, dependencies, etc. are all in git already and can be highlighted there if appropriate. For general comments, git notes covers that. Business (ie. $work) will dictate whatever it wants and that is what get used but for anything I personally have control over, everything goes in the repo itself to prevent platform lock-in. For example, github's been going downhilll lately but all those projects with their history in PRs, etc. now needs to exfiltrate all that data somehow.
  - xorcist 4mo ago
    Jira contains discussion and requirements. It can meander for months before the right action is chosen. It can be important to have background, but it replaces the mailing list discussion that led up to the change, it does not replace the commit message. The commit message is writen in retrospect and is written for someone with the code in front of them to explain why this change was made, and why it was done in this particular way. If your commit message is too short then than is your problem right there. The easy fix is you taking five seconds out of your busy day to save an hour for you readers. Have you seen how commit messages are written for git itself, or for the Linux kernel? Let me help you by linking the currently latest commit in the github mirror of git, it is not chosen to be particularly good or bad but is pretty representative of how git developers write commit messages: https://github.com/git/git/commit/b809304101 https://github.com/git/git/commit/b809304101 As you can see, without knowing much of the specifics of the code, we can get an idea why this change was made the way it was. There is a certain art to writing short and concise commit messages, but the same is true for code itself. Some, but comparably very little, practice is required.
oskarpearson 4mo ago
The handling of ticket numbers is covered in the FAQ (scroll to the bottom) [edit] At the bottom of https://scopedcommits.com/ https://scopedcommits.com/ I mean
calvinmorrison 4mo ago
fixes/feature labels help when generated semver and doing changelogs if you publish them externally or internally. JIRA tickets can help to, its about giving context to why the commit exists. I find the 'component' label most helpful in large monorepos.
splix 4mo ago
Exactly. The commit message is supposed to be for the future developer, not to generate changelog. And the main case when that developer reads the commit message is when he doesn't understand _why_ that commit exists. Not what it changes, but what is the purpose of certain lines. So he runs "blame", sees commits, the original developers are not with the company anymore, the old JIRA may not exist too, and the only hint is the commit message. https://dev.to/splix/the-why-behind-the-code-2bb1 https://dev.to/splix/the-why-behind-the-code-2bb1
Ferret7446 4mo ago
This, along with the "successful git branching model", are symptoms of the fact that devs overwhelmed with the flexibility of git and look to other people to define standards for them because they that lack the experience to do so for their own requirements. Actually, this is also similar to classic OOP, where people use a contrived method of structuring their code.
omcnoe 4mo ago
Scope is crucial when working with multiple teams/projects in a monorepo.
- arcticfox 4mo ago
  Exactly. I think it's funny / telling that my team analyzed Conventional Commits and came to the exact same conclusion the author did. Scope might not be important to every project, but the feat/bug etc taxonomy might be the least useful focus of them all.
- procaryote 4mo ago
  One of many problems introduced by monorepos

literallyroy 4mo ago

Is the benefit of using a separate source that you can include images or something else I’m missing? Couldn’t you include context in the commit body?

SamuelAdams 4mo ago

It is useful if you automate generating release notes. Then your notes are grouped by new features first, then bug fixes after. This makes it a little easier for non-technical uses to read.

pseudalopex 4mo ago
Commit messages are good release notes rarely.
- llimllib 4mo ago
  it's usually a "something is better than nothing" situation. If you have somebody willing to write custom release messages, that's definitely better; but conventional commits is better than nothing for it.
  - ralferoo 4mo ago
    Absolutely not. Commit messages should never be automatically passed through to the end-customer. I also worked in a place that tried it once and it was a disaster. Sure, a list of commit messages can be a useful start as a list of things that might want to be put in the release notes, but very rarely is the developer the right person to be explaining those changes to the end user. If a developer is being asked to do that, it's a good sign that the PM isn't doing their job properly.
  - pseudalopex 4mo ago
    They did not say generated release notes are useful if you care so little you would write no release notes without them however.
- nkrisc 4mo ago
  You can have a writer re-write them into acceptable release notes. It gives them a good and accurate starting point.
  - pseudalopex 4mo ago
    Closed issues are a better starting point in my experience.
- mystifyingpoi 4mo ago
  That's right, but with AI help + some hallucination you can get nice looking release notes out of the worst mess of commits.

adammarples 4mo ago

Pretty much everywhere I've worked recently enforces some kind of jira ticket number in the PR title

procaryote 4mo ago
Perhaps it's useful to ask why? What does the jira ticket give you that a longer PR message can't do better?
- adammarples 4mo ago
  Saves you a click maybe, at least it's easy to always know what ticket you're working on right in the terminal

dualvariable 4mo ago

This is the way we did it when we used JIRA. For GH issues you can always navigate back to the PR discussion (which should have linked issues and other pointers in it) from the commit. Of course when we switched to GH issues, we largely abandoned JIRA and years later the instance got turned off and deleted. Now all those JIRA tags are entirely useless. IMO that actually argues for tight coupling between your issue tracker and your git repo. And what you really want is portability (which I don't see how you get other than with tight coupling). Ideally there would be open standardized formats, but as it is, github is the 800# gorilla that defines the format and as long as gitlab and other clones can slurp in github project metadata (or at least PRs) then that effectively gets you closer. But any way... Fixed, immutable pointers to an Atlassian product that you might not be using in 5 years is not a good policy. I'd sooner accept the policy that the git commits needed to stand entirely on their own and all the information about the "why" of the change needed to be baked into the git commit or the comments in the source (I think that fails, though, since everyone is overly terse in git commits and summarizes issues and loses information--and the back-and-forth dialog in a PR discussion is useful because it contains more than just one person's voice summarizing the reason for the change).

mystifyingpoi 4mo ago
> we largely abandoned JIRA and years later the instance got turned off and deleted Sorry to be nitpicky, but why did you abandon a tool that contained a lot of valuable knowledge? That's not the fault of GH nor JIRA, that's your fault. At least you'd back up descriptions + comments from these JIRA sources.
- oskarpearson 4mo ago
  Like many tools defending their moats, tools like Jira don’t make it easy to get one’s data out.
  - ralferoo 4mo ago
    That isn't true though. It's very easy to export your data from JIRA. From your board, go to the List tab, filter the items to whatever you want, and then click ... and you can export the data in various different formats. Exporting as XML dumps everything.

chickensong 4mo ago

> Similarly "bug", "fix" or "feature" adds no useful value. If you're not using/tied to an issue tracker, embedding tags like these in git gives you some basic metrics.

eikenberry 4mo ago

> The only thing I've found useful, and which the article doesn't even consider, is a link / id for the relevant change request. The commit already contains all the information about what was done in the change, what's missing is the context about why. The "why" is THE thing that needs to go in the git commit message. Capturing "why" is the entire point of that message and slapping a link to some external (and eventually absent) resource is not a good substitute.

mmcnl 4mo ago
It is a good substitute. 1. Usually the commit message is often too short to capture the "why" adequately. 2. It is very beneficial to capture the why in one single source of truth, and that usually is not the Git commit message in a business context. Hate on Jira all you want, but if you capture the "why" there, you can add comments, view history, add rich context, link dependencies, add rich context, etc. Can't do that in a Git commit message.
- jsve 4mo ago
  You can put that in the body of the commit message, not everything has to go in the subject line.
- eikenberry 4mo ago
  My ire is more directed at github PRs than Jira... but the same basic idea applies. You want a single source of truth and you want that as close to the origin (the code) as possible. Your history, dependencies, etc. are all in git already and can be highlighted there if appropriate. For general comments, git notes covers that. Business (ie. $work) will dictate whatever it wants and that is what get used but for anything I personally have control over, everything goes in the repo itself to prevent platform lock-in. For example, github's been going downhilll lately but all those projects with their history in PRs, etc. now needs to exfiltrate all that data somehow.
- xorcist 4mo ago
  Jira contains discussion and requirements. It can meander for months before the right action is chosen. It can be important to have background, but it replaces the mailing list discussion that led up to the change, it does not replace the commit message. The commit message is writen in retrospect and is written for someone with the code in front of them to explain why this change was made, and why it was done in this particular way. If your commit message is too short then than is your problem right there. The easy fix is you taking five seconds out of your busy day to save an hour for you readers. Have you seen how commit messages are written for git itself, or for the Linux kernel? Let me help you by linking the currently latest commit in the github mirror of git, it is not chosen to be particularly good or bad but is pretty representative of how git developers write commit messages: https://github.com/git/git/commit/b809304101 https://github.com/git/git/commit/b809304101 As you can see, without knowing much of the specifics of the code, we can get an idea why this change was made the way it was. There is a certain art to writing short and concise commit messages, but the same is true for code itself. Some, but comparably very little, practice is required.

oskarpearson 4mo ago

The handling of ticket numbers is covered in the FAQ (scroll to the bottom) [edit] At the bottom of https://scopedcommits.com/ https://scopedcommits.com/ I mean

calvinmorrison 4mo ago

fixes/feature labels help when generated semver and doing changelogs if you publish them externally or internally. JIRA tickets can help to, its about giving context to why the commit exists. I find the 'component' label most helpful in large monorepos.

splix 4mo ago

Exactly. The commit message is supposed to be for the future developer, not to generate changelog. And the main case when that developer reads the commit message is when he doesn't understand _why_ that commit exists. Not what it changes, but what is the purpose of certain lines. So he runs "blame", sees commits, the original developers are not with the company anymore, the old JIRA may not exist too, and the only hint is the commit message. https://dev.to/splix/the-why-behind-the-code-2bb1 https://dev.to/splix/the-why-behind-the-code-2bb1

Ferret7446 4mo ago

This, along with the "successful git branching model", are symptoms of the fact that devs overwhelmed with the flexibility of git and look to other people to define standards for them because they that lack the experience to do so for their own requirements. Actually, this is also similar to classic OOP, where people use a contrived method of structuring their code.

omcnoe 4mo ago

Scope is crucial when working with multiple teams/projects in a monorepo.

arcticfox 4mo ago
Exactly. I think it's funny / telling that my team analyzed Conventional Commits and came to the exact same conclusion the author did. Scope might not be important to every project, but the feat/bug etc taxonomy might be the least useful focus of them all.
procaryote 4mo ago
One of many problems introduced by monorepos