[icedchai]

Some orgs have strict change control processes. "Why is this change happening? What is it supposed to do?" At one place, I used to just submit my own ticket,a assign it to myself, then open a PR linked to it. Totally pointless. At some other companies, it's more open. "We trust you! Just get it done." There is more risk, but it's a better environment for some. Possibly not for all.

[sanderjd]

I understand requiring such documentation and auditing history, but there is no good reason (or at least nobody has presented one here yet) to do it in both a ticket and a PR.

[rleigh]

Have you worked in a regulated environment? It can be a regulatory and legal requirement to do this, since it's part of the software development lifecycle processes which are required to be followed.

At its core, this is about ensuring that the software is not changed without a documented requirement to do so in the form of a formal change request. The PR alone does not do that. The PR is the software change. It is not the request to do the change in the first place.

Some projects and company processes can be sufficiently lax to permit developers to open PRs and change things without any additional accountability or oversight. In these cases, you don't need that extra level of work. But many projects do need this, and it can provide value even outside a regulated environment. Many open source projects require a corresponding ticket for every change as well.

You might also need to make sure that the work meets the "definition of done". In a stricter environment, that can mean making sure that every change ties back to the design documentation and the system requirements, as well as having all of the necessary test and documentation coverage to match, and more. That gets tracked on the ticket, not the PR, because the PR is only about the software change, not the higher-level stuff.

Another factor is that the ticket is what has the visibility. Not everyone in the company is necessarily directly involved with the nuts and bolts of the version control system. When it comes to the higher-level aspects of project management, particularly on large projects with multiple teams, you aren't going to be doing that with GitHub, but you do need to coordinate activity and account for where the development effort is going for planning and resourcing purposes, even if the metrics are only used within the team.

None of this means being hidebound by process. For a trivial documentation change or bugfix, there's nothing to prevent keeping this overhead to the bare minimum. It takes 30 seconds to create a new ticket before opening the pull request, with a title and possibly a sentence or two description. That can greatly help the other people in the company see what is being worked on, what's been fixed, what's in the backlog and where effort is being spent. Ultimately, we aren't writing software just for our own amusement, we're doing it for others, and the tickets are part of communicating and coordinating our activities with other people, even if it appears superficially onerous.

[sanderjd]

Can you give me example regulatory language that would require a Jira ticket in order to change internal documentation? (That is the only thing we are discussing in this thread, despite many attempts to broaden it.)

An internal engineering documentation change is not something that needs visibility in this grand project management effort. Project managers that are tracking such things are doing busywork that is not adding any value.

I recognize that all of this is very common, but it's not actually valuable. I have absolutely zero problem abiding by rules that are not good, but what I see a lot of here is learned helplessness and rationalization. It is not necessary to convince oneself "actually this is all good" in order to merely abide by rules that it is not your responsibility to change. You can merrily follow the rules and then also, if anybody asks you, you can say "these processes are not valuable for the following reasons".

[rleigh]

The documentation itself can be regulated, and changing it requires more than a PR code review by another software developer. As an example, the instructions for building and releasing the software could come under the controlled SDLC process.

I see where you're coming from, but you're not correct that this is misguided, nor that this is just busywork for project managers. If you're doing safety-critical stuff in the automotive, aviation or medical industries then process faults mean lives could be put at risk. A drive-by PR to update a document could have serious implications, and that's why change management processes are in place. They are a safety-net above the level of the code review and activity in the VCS, because you have a different set of eyes on what's going on.

[sanderjd]

I know there is some fallacy or something around asking for evidence (is it "sealioning"?), but are you aware of anything that demonstrates that this kind of change control process successfully reduces risk in life-critical systems? I'm very skeptical that requiring a ticket requesting an internal documentation change in order to improve that documentation is saving any lives. You might say "well it can't hurt", but I don't think that's obviously true; I think it creates a perverse incentive to leave documentation as is rather than improving it, which I think is more likely to be negative sum than it is to be valuable. That is why I think it is misguided; I think it is more likely to result in poorer documentation, for no gain.

Please understand that I really am just talking about this one case; I see no reason to question a requirement like this for changes to code or configuration or interface documentation or specifications or anything else.

[relaxing]

An example is when all hours spent need to be traced back to a requirement that has been signed off on by stakeholders. There needs to be a recordkeeping system to support this requirements traceability, so Jira it is.

[sanderjd]

Is that a regulation? It sounds like either an internal process choice or a contract requirement.

Edit: But point taken. I can see where this would be a (misguided, counterproductive) requirement in a probably-government contract. I would just suggest recognizing that it is a necessary evil when doing that kind of work, but not a good practice.

[icedchai]

At a previous org, I discovered most of the product management folks did not have access to github. So if someone (not an engineer) was trying to figure out why Joe changed feature X, they couldn't do it with a PR. They only had access to Jira.

[sanderjd]

Sounds like a good thing to fix.

Edit to add: But also it seems like there are two things going on in this thread. On the one hand, the reason for tickets is (supposedly) for a compliance audit log. And surely the auditing system could read from both Jira and GitHub. But this question of what product managers can access is a different one. I think the more likely reason for these rules is for "product managers" who are really acting as project managers and are trying to micromanage through tickets.