Git and GitHub for Product Managers
Keeping the Trail Intact
The reason to care about linking is that in nine months someone will ask why a behaviour works the way it does. If the trail holds, you can answer in two minutes. If it doesn't, nobody will ever know.
THE TRAIL THAT SURVIVES
Support ticket #8814
| references
v
GitHub issue #331 "Payment skipped on the 31st"
| "Closes #331" in the PR description
v
Pull request #412
| merged
v
Commit a7f3c21 "Fix scheduled payments... See NG-884"
| included in
v
Release v3.14.0 (21 March)
Every arrow is a link somebody took two seconds to add.
Together they answer "why does this work this way?"
nine months later, without anyone remembering.
'Closes #331' Is a Real Instruction
Writing 'Closes #331' or 'Fixes #331' in a PR description makes GitHub close that issue automatically when the PR merges, and permanently links the two. It costs nothing and it's the single link most often missing. Worth mentioning to your team once.
COPY THIS PROMPT — Writing a Bug Issue
Help me write a GitHub issue for a bug that engineers can act on
without coming back to me with questions.
WHAT I KNOW
What's going wrong: [describe it]
Where it happens: [which part of the product]
Who reported it: [support tickets, a customer, you noticed it]
How many people affected: [if you know]
What it costs them: [what the customer experiences]
Please write the issue with these sections: title, what happens,
what should happen, how to reproduce, evidence, and impact.
Then:
1. Flag anything in my description that's ambiguous and would
generate a clarifying question
2. Tell me what information I'm missing that an engineer will
ask for, and where I could find it
3. Suggest labels for this issue
4. Draft one sentence for the impact section that would make
the priority obvious without overstating it