13

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
2
  • 8
    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.
    – Ixrec
    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.
    – user53019
    Jan 22, 2016 at 20:07

4 Answers 4

Reset to default
17

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
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.
    – harpun
    Jan 23, 2016 at 9:49
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
1
  • 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.
    – user42386
    Jan 23, 2016 at 4:02
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
2

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.
    – Jacob Sparre Andersen
    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.
    – machineghost
    Aug 23, 2016 at 20:51

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.