14

I was wondering if it would be good practice for commit messages to contain the ticket number they were apart of. It would be like 

    2568 Fix heating issue

    Summary of the issue with a bunch of detailed comments

It would be a bit of a pain to get the ticket or isse # in each commit and I am wondering if people think it would be worth it in the long run. Also if my branch has the ticket number is this redundant? The main issue is that I use source tree and that in the log / history view it can get a little complicated to see what commit corresponds with what ticket. I just would like a better way to see how everything works.

Improve this question
3
  • 10
    Unless you have really long ticket numbers, or some weird tool that only shows the first 10 characters of each commit message yet is still useful for some reason, I can't see any downside to this. Where I work we do this all the time. Commented Jan 22, 2016 at 20:05
  • It's convenient, but it also isn't worth going to extensive lengths towards making happen. It helps you identify why a change may have been made. But you have to weigh that against the frequency of how often you need that information and what comparable benefit it actually provides versus the cost of implementing this approach. Commented Jan 22, 2016 at 20:07
  • I prefer to put the ticket number in the feature branch name rather than the commit message, but it's not a hill I would die on. Commented Jan 28, 2024 at 22:16

5 Answers 5

Reset to default
19

Yes, this is a good idea and fairly standard (but not universal) practice.

The specific software engineering goal you are achieving with this is requirements traceability. The idea is you want to be able to trace a requirement through the entire software process:

  1. Business requirements
  2. Functional requirements
  3. Technical requirements
  4. Code artifacts
  5. QA feedback
  6. Development fixes

By using ticket or requirement numbers (e.g. Jira story IDs) in commit messages and any correspondence, you are working toward that software engineering goal.

If I come back a year later and see the commit message, I can look up that number in another system to get the full background behind the requirement or ticket, including anything that occurred after the commit.

Improve this answer
2
  • 1
    Very often it's also an audit requirement - being able to trace any code change that went into production and connect it with documentation of the business requirements. Commented Jan 23, 2016 at 9:49
  • The traceability argument is valid. But, would there be any reason not to place the ticket number in the description instead? Adding the ticket number shortens the limited available space of the commit title which could be spent on adding more immediately relevant information that doesn't require opening an external link. Commented Jan 28, 2024 at 11:11
3

The downside is that people will write less complete commit comments because someone can go to the ticket for more details. This is only really a problem if you say switch to a different ticketing system and can't keep the history or someone doesn't have ticketing system but does have access to the repository.

If the branch is already named for the ticket I wouldn't bother putting it in the commit, that does seem redundant.

Improve this answer
2
  • 2
    Consider CI systems like Jenkins, which know nothing about branches, just commits. If you want to tie Jenkins back to eg JIRA, to put build-related comments on JIRA tickets which some people think is a useful thing to do, then you need the ticket number in the commit. Or, take git bisect. It reports to me what commit it's on, and in some cases it would highly useful to have the ticket number in that commit msg. Commented Jan 23, 2016 at 4:02
  • 2
    Branch names in some VCS's are strictly temporary; in git, there is no way to look at a commit and determine which branch the user had checked out when it was made, the only place where a ticket can be referenced is the commit message. Commented Jan 28, 2024 at 17:54
3

If your system tracks all features/bugs then you likely will have a ticket of some sort. But if your system only tracks bugs (for some reason?) and all new development is a free for all.

Some significant advantages:

  • Some VCS/ticket systems allow auto hyperlinks for the ticket number when browsing the commits in the issue tracker (this is super useful, see github, redmine)
  • It provides some context for the inevitable "why did Simon do this? Makes no sense!" question
    • Often this might be years later...
    • Context for changes can take a lot of work multiple years in the future. Having a ticket with an explanation for why the code was changed can be super, super useful
  • Helps keep people working on value-add things
    • "Oh, I'm going to refactor this.. and this.. and this... and... oh I've not done any value-add work in a week!"
  • Can allow searches to find commits related to an issue

The only disadvantage is if your team doesn't really use tickets or a tracking system. Then it'd be harder to find the ticket number. Or if your VCS and issue tracker don't integrate well.

And... you should track all efforts somewhere, so, if that's why you are not using a ticket system for nearly all of your work I'd strongly suggest doing so, regardless of whether you have it included in your commit messages.

Improve this answer
3

Including reference numbers (tickets, features, requirements, etc.) in commit messages is a great idea. But it should never be a substitute for a good message. At my current employer, we're now on our second source control system, our third ticketing system, and our second requirements management system. Needless to say, the old systems' data were never migrated into their replacements, and even if they were, the numbering systems overlap.

Improve this answer
2
  • With one of my current customers the problem of overlapping numbering systems is managed by prefixing the reference number with the name of the current issue management system. Trivial, but very practical after a few changes of issue management systems. Commented Jan 23, 2016 at 18:16
  • If your company can't handle migrating data when you adopt new systems, I think git commit messages are the least of your problems. The practice of just including the ticket works great for well-run companies who have only a single bug tracker, so I think it's poor advice to tell others to optimize their practices to fit the practices of poorly-run companies. Commented Aug 23, 2016 at 20:51
0

As one of the current answers points out, referencing a ticket number is important for traceability. This can be relevant to:

  • Understand the higher-level perspective on why changes were made. You should aim to make commit messages self-contained, i.e., so they can be understood in isolation. But, when you are interested in understanding how multiple commits all work together towards a common goal, ticket numbers which link to external documentation come in handy. Note: pull request descriptions on GitHub fulfill a similar function, but depending on your software development process, ticket descriptions tend to be more end-user oriented, and pull request descriptions more technical. Also, you may not want to depend on a specific version-control system feature.
  • Fulfill legal requests such as audits.

However, I personally feel it's better to reference ticket numbers from commit descriptions instead of their title.

The commit title should be concise and acts as a summary. Adding a ticket number to a commit title steals some of the precious space which could be used communicating whether the particular commit is relevant to whoever is reading a commit history (titles are clipped past a certain point in many tools visualizing commit histories).

In contrast, a commit description allows adding additional detail/motivation; exactly what you would expect to see when you open the linked ticket number, i.e., the "higher-level perspective" described earlier.

Furthermore, ticket numbers without an explanation can be ambiguous. Often, work is performed as part of working on a particular ticket which may not be directly related to it. E.g., refactoring work in preparation of implementing an actual feature. Somebody looking for documentation in the referenced ticket number may get more confused than before if what is described there is not clearly related to the observed changes.

Therefore, I would argue ticket numbers belong in commit descriptions instead, in which they can be prefixed with clearer intent, such as "Preparatory refactoring for XXXX."

Improve this answer
8
  • A big advantage to putting them in the commit title / first line is that you can look at the log for a set of commits and quickly see how they group into tickets. A consistent placement like "1234 | Preparatory work for adding feobnicator" also allows tools to reliably scrape out the ticket number, which is much harder if the ticket is just mentioned somewhere in the middle of a paragraph of text. Commented Jan 28, 2024 at 18:01
  • @IMSoP The former, I would consider an anti-pattern. If that type of grouping is relevant while looking at commit histories, you are probably investigating at the wrong level of detail. Personally, I'd look at PR histories which give just that. If you want scraping, you probably want consistency and automation. You could add a PR's issue number by default in rebased commits description with a scrapeable prefix. Commented Jan 28, 2024 at 18:16
  • Put differently, the "preparatory commit" shouldn't focus on the preparatory nature at all; that shouldn't be in the title. It's focus should summarize the actual work; what the preparatory work consisted of. That may be wholly unrelated to the issue number which simply gave rise to it. Commented Jan 28, 2024 at 18:22
  • At least in git, the commit message is all you have. If you want to reference back to a particular PR, it has to be in the commit message somewhere; if you want to scrape out metadata for a changelog, it has to be in the commit message somewhere. You might use a different convention for commits you know you're going to rebase/squash - they're only need to be useful for a short time; or you might use a different convention for merge commits; but if you want to answer a question like "which tickets have been worked on since the last tag", you have to put it in the commit message somewhere. Commented Jan 28, 2024 at 19:11
  • 1
    You said "I'd look at PR histories"; I'm saying that's only possible if you have the PR reference in a consistent place in the commit message - which is just another type of ticket reference, generally at one remove from the main ticketing system. That could be in the description, with a fixed phrasing like "Fixes #123" on its own line, but prose like "This is an initial fix for issue 123, with a follow-up ticket raised" doesn't provide the same functionality to later scraping. Commented Jan 28, 2024 at 19:46

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.