If you are in a regulated environment or selling to large enterprises you may find that having a SDLC policy of “no changes without ticket to track” is a more easily defensible control against unauthorized code changes (you’ll get asked about this in SOC2 and security questionnaires). The policy “anyone can make a change if they find a reviewer to approve” might not float.
Mandating ticket IDs can be really annoying though, for example if I want to make a few-line no-op refactor to clean up some code, I don’t want to have to create a ticket. So it’s definitely a tradeoff.
Great commit messages are just one part of the timeline. Ensuring there's a link between the commits/PR and the ticket lets the future detective get more information (frequently, that's "why did we do this").
There's nothing wrong with fixing a bug you discover upon inspection. Forcing tickets for every change discourages code maintenance.
See DeGrandis’s “Making Work Visible,” the hazard of “link to a ticket if it exists” is that sometimes this causes us to treat tickets as an external process, but we absolutely want to surface tickets that track our cleanup of tech debt and any other procedural tasks that we are stuck doing.
If automated tooling sounds nice but you are at the sort of place where “there are three priority levels: hot, Red Hot, and DO IT NOW,” this can also be part of a pull request template. One extremely effective template we used at a previous job just had quick checklist and you'd check off for example “I tried this code on my dev cluster.” Caught a lot of “whoops I am moving too fast and need to slow down a bit” issues, hah!
I feel like I disagree here.
Turning on Git Annotations in any JetBrains IDE and seeing who made changes, when and which Jira issue necessitated these changes right there is pretty useful. All of the sudden, you can easily say: "This method had been changed in 5 different commits in the last 3 years, what I probably need to read before making my own changes are issues ABC-123, ABC-236, ABC-455, ABC-855 and ABC-1233, to understand the business context and historical limitations behind all of this."
> Just use the commit message and in pr review enforce commit message norms.
I fully agree with this, but unless you squash your commits or rebase, finding out which MR/PR a particular set of changes belongs to isn't always immediately doable, especially when looking at things locally instead of the GitLab/GitHub UI.
Furthermore, the barrier of entry is higher: I always describe my changes and add a bit of context in the merge request/pull request description, sometimes even with GIFs or MP4 video demonstrations of what happens as a consequence of them. And yet, the majority of other developers have no desire to do that - I've regularly seen people leave those empty, and even commit messages are sometimes like: "try fix" instead of "make Ansible ensure that file permissions are set to have the newly created directory be readable by the group that will run the app".
In contrast, everyone is capable of adding a simple identifier to the issue management system and there are very few arguments that they can make against adding a few characters to the beginning, as opposed to: "But adding descriptions would take a lot of time and slow down development, I don't think we really need those because you should be able to read the code and understand everything."
Sure, you can enforce it in a top down manner, but it can be like pulling teeth at times, so you might as well ensure that at least the lowest common denominator is in place, before trying to find better approaches.
Exceptions to this might be small changes that don't really correspond to an issue, then you have two choices:
- create an issue yourself so the work doesn't become untraceable in the issue management/billing system you use
- just leave a short text description without issue identifierThis should be what a commit message is. Commit messages should describe the rationale behind the change.
Ticket numbers are great for linking commits together. But they should not have to be relied on to find out why a change was made. Ticketing systems may come and go but commit messages persist.
In theory I agree. In practice, I've yet to see it work out that way - there are always discussions with clients/other departments in the ticketing system which will never appear in the commit messages. References to logs, screenshots/animations of the issue and other things that give the full context to why that change matters.
That's also why I believe that code alone is not enough - you need code comments to explain not what the code does, but why it does it that way etc., it's just that ticketing systems can provide even more of the surrounding information which also doesn't fit either in commit messages, or in code comments.
> Ticketing systems may come and go but commit messages persist.
I'd say that everything comes and goes, but in most cases you won't have to worry too much, since most information will be kept around in some capacity, like migrating SVN revision messages to Git commit messages (though even that wasn't always quite possible, in the case of non-standard repository layouts, since most migration scripts broke) etc.
Though with how deeply integrated some companies out there are with solutions like Jira, I doubt they'll ever rid themselves of it.
You can check in git if work has actually begun, and you can get from and old commit to Jira by virtue of the merge commit.
I don’t know how you’d do it in a non-mono repo setting
Stories can last for a while, but long-lived feature branches have to be kept in sync with the main branch, otherwise they develop nasty merge conflicts and you are not deploying continuously.
I think the better solution is for your versioning and your issue tracker to be integrated: we still expect every developer to merge to mainline one or twice a day[1], keeping merge conflicts shallow... But they should mention what issue they are working on in the commit, and the integration dumps that information into the tracker automatically.
[1] This is not hard to make safe, though it makes a lot of devs skittish at first. See Three-Flow for a non-CD version, https://www.nomachetejuggling.com/2017/04/09/a-different-bra... as a stepping stone. One key thing is that code review needs to become much lighter than it is at many organizations, “I don't care how you did it as long as it can be turned off with a feature toggle and does not break prod or introduce security vulnerabilities when I merge it: those key things are what I am looking for.”
Does this not lead to poorly-written features that drag down future development yet cannot be turned off because they have grown important for the business?
At least that's my experience with not regulating at least a basic level of code quality in the review. What are you doing differently to prevent that?
That approach makes a lot of sense to me. Link the commit to the ticket when it enhances future reading, but not out of blind application of principle.
I have dealt with bugs that were thought to be fixed a long time ago, only for them to mysteriously pop up again later. Ticket is created and the old ticket is linked.
It's really helpful to see what was done 2 years ago, including the attempted fix that is now still live in the code base but apparently doesn't work properly.
That said, as always, it's not black or white. There are definitely cases where it doesn't make sense, but I don't think you should call it 'totally worthless'.
This is one of the things that sound 'good' on the surface and are totally worthless in practice (especially when practicing minimal commits).
In the wild this devolves into a meaningless umbrella issue (Deliver Feature Foo) or 1 liner issues that sometimes did not even match the pr contents.
Just use the commit message and in pr review enforce commit message norms.