What makes a good JIRA ticket? Laconic description in a "placeholder" ticket might be good for the start, but after several days anyone would forget what was it all about.
Lately I was solving a minor bug which lead me into some routine investigation. I added some comments in Jira and submitted a MR. Then one of my colleagues accepted the MR and posted this on Slack:
Kudos to the whole documentation. This is for me a perfect best practice example of how a ticket from reporting to solving should look like.
Jira Ticket had a url of where it happened, images of the bug (problem), images of the expected behavior. Nice commenting of the problem after analysis and proposed solution. Great overview in the MR.
It wasn’t my domain but I could follow it perfectly and checked the branch out locally to verify that it works.
Wow. This comment was more than flattering and it came unexpectedly, so I assume it was honest. I have decided to share the procedure so more people can make their co-workers happy 😁
The ticket was nicely prepared from the start. It had the following sections:
- problem (with pictures)
- expected outcome (with pictures)
- extra (additional comments)
Nice example of a template:
## Summary *short summary* *link JIRA ticket if applicable* ## What is affected? *feature(s) affected, platforms* ## Steps to reproduce *how one can reproduce issue (screenshots, metrics etc.)* ## Solution *describe what is being changed by this merge request* /label ~BUG
2) Use Labels
I ❤ this one. It prevents you from accidentally merging stuff and helps to organize your drafts
- keep functionalities in smaller, separate commits, then squash them 😲, i.e.:
Removing unnecessary image
Added functionality X
- avoid removing too many empty lines or reformatting files because it decreases readability and draws attention away from the important stuff
- if you really need to clean-up/reformat, do it in a separate MR
- explain what is actually happening but try to keep it simple
- give tons of examples
- paste urls to images and related pages (both broken and correct but mark which one is which)
- add screenshots and attach files/database dumps/scripts
- use markdown, it improves readability
- use colors to distinguish between positive/negative (ie. green/red)
- if you don’t have automatic Jira/Gitlab integration, manually paste the links to MR to keep the history log
- suggest several options so stakeholders can make decisions
- paste links to connected issues in the past
- suggest additional bugfixes/create more tickets and link them
- keep a little diary of your activity, it will help reviewers to follow your thoughts
- radical transparency
- documented train of thought
- everything linked in one place
- markdown, emoticons and colors
- pictures, pictures, pictures
- links, links, links
- give options, discuss solutions
I hope this article might help someone in their daily work 😁 Let me know what you think in comments!