DEV Community

loading...

I accidentally a perfect JIRA ticket

aniawyrwinska profile image Ania Wyrwinska ・2 min read

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.
Bravo!

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 😁

How to prepare a Jira ticket

The ticket was nicely prepared from the start. It had the following sections:

  • problem (with pictures)
  • expected outcome (with pictures)
  • extra (additional comments)

How to prepare a GitLab MR

1) Use MR templates

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

Sample label:

/label ~BUG

3) Use WIP flags

I ❀ this one. It prevents you from accidentally merging stuff and helps to organize your drafts

How to commit

  • keep functionalities in smaller, separate commits, then squash them 😲, i.e.:
    • Removing unnecessary image
    • Small refactoring
    • 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

How to comment

  • 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

Pros:

  • radical transparency
  • documented train of thought
  • everything linked in one place

Cons:

  • time-consuming

General tips:

  • 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!

Discussion (2)

pic
Editor guide
Collapse
lbonanomi profile image
lbonanomi • Edited

From someone who has earned their living grinding-out tickets for the last 20 years, thank you. A thoughtful explanation or update to a ticket is a rare diamond found in my SysOps coal mine.

Collapse
aniawyrwinska profile image
Ania Wyrwinska Author

Thank you!! I'm super happy you liked it! :D