OpenMRS Jira Clean Up Protocol (aka "Quarterly Graveyarding")

By Grace Potma
4 min

Why:

We can’t show our community that Jira is a serious, meaningful place, unless we are humanly able to use it meaningfully and see what issues really matter. To keep Jira up-to-date, many software organizations routinely bulk-close old issues that are older than a giver time period. This is helpful for us at OpenMRS because otherwise our backlog quickly becomes too huge and old to be helpful. Simply leaving tickets endlessly open can become unsafe, since the noise can obscure critical issues that still need addressing.

This doesn't mean we just throw out old ideas and bugs that are still useful: the process described here helps ensure that still relevant & important issues remain, and even those that are bulk-closed are not actually deleted. (Further details and history here.)

When:

~Quarterly. Our rough goal is to keep our average issue response time (time from reporting to closure) less than 1 year.  

We also only close issues that have not been updated in >1 year. For example, an issue created in 2003 that has been updated or worked on within the last 12 months would not be a Graveyard Candidate. 

Who:

A trusted community member with Admin permissions for the Issue Tracker. 

How:

Part 1: Initial Investigation (3-4 weeks before closure)

  1. JQL: Date range. Filter out itsm. 

    JQL (Advanced Jira Search parameters)

    resolution = Unresolved AND updatedDate < [YOUR DATE MINUS 1 YEAR, as YYYY-MM-DD]



  2. Review the issues that come up from this search. Especially review any issues labelled as Blocker, Must, or Community priority, as you may realize these issues should be kept. (eg you can add:  AND (priority = Blocker OR priority = Must OR labels = community-priority) to your JQL search criteria to check for blockers, musts, and priorities. 

Part 2: Bulk Warning Notification (3-4 weeks before closure)

  1. JQL: Date range. Filter out itsm. 

    JQL (Advanced Jira Search parameters)

    resolution = Unresolved AND updatedDate < [YOUR DATE MINUS 1 YEAR, as YYYY-MM-DD]



  2. Click "Tools", then click Bulk Change "all X issues". Select all issues. Click "Edit Issues".

  3. Operation Details:

    1. Select "Change Labels", and Add to Existing the Label:



      Graveyard_CANDIDATE



    2. Also Select "Change Comment", and add the comment: 

      *Quarterly Clean-Up Notice* This issue has not been updated in >1 year, and so has been identified as a Graveyard candidate - i.e. it will be auto-closed in 2 weeks. If you want to keep this issue open (e.g. because it remains a priority or important thing to fix), please add a comment here explaining why, and remove the “Graveyard_CANDIDATE” label. For questions, you can reach out to [YOUR NAME].



  4. Should you send mail for this update? The general rule of thumb is not to send mail for these updates, since this spams folks' inboxes. However, it is fair to send mail for this update if there are <100 issues, so that the original reporters are updated that something has been closed. 

  5. Complete the change.

  6. Notify the community with a Talk post (like this one), with link to issues labelled "Graveyard_CANDIDATE". Tag anyone who comes up frequently as either a reporter or assignee in the list.



Part 3: Closure (after the timeline has passed)

  1. Search for your graveyard candidate issues:

    JQL (Advanced Jira Search parameters)

    labels = Graveyard_CANDIDATE



  2. Click "Tools", then click Bulk Change "all X issues". Select all issues. Click "Edit Issues".

  3. Add new Graveyard-DATE labels:

    1. Operation Details:

      1. Select "Change Labels", and Add to Existing the Label: (e.g. "Graveyard-2022-02")



        Graveyard_YYYY-MM



      2. Also Select "Change Comment", and add the comment: 

        *Automatic Closure: No updates in >1yr* Automatically closing this ticket as per [our quarterly Graveyard process](https://wiki.openmrs.org/x/RAvDDw). If anyone becomes aware of a reason this ticket should be brought back to life, or if you have questions or concerns about closing this issue, please simply: 1. Re-open the ticket 2. Remove any “Graveyard” label(s) 3. Add a comment explaining why this ticket is still important or should be addressed. If there is a particular site or organization counting on this work please also mention that. Why we close issues that haven't been updated in >1yr: Regular "graveyarding" helps us keep our Jira tidy, and helps prevent critical issues being missed due to too much noise.



  4. Should you send mail for these updates? The general rule of thumb is not to send mail for these updates, since this spams folks' inboxes. However, it is fair to send mail for this update if there are <100 issues, so that the original reporters are updated that something has been closed. 

  5. Complete the change.

  6. Remove the Label "Graveyard_CANDIDATE"

    1. Complete steps 1 and 2 again to do another bulk update to all your "Graveyard_CANDIDATE" issues. This time, "Change Labels" and "Find and remove these": "Graveyard_CANDIDATE".

  7. Close the Graveyard-DATE issues

    1. Search for your graveyard-DATE issues: (e.g. "Graveyard-2022-02")

      JQL (Advanced Jira Search parameters)

      labels = Graveyard-YYYY-MM AND resolution = Unresolved



    2. This will show you all the issues you want to clean up, that are not yet officially "closed".

    3. Usually, there will be issues from different projects that have different workflows. This means we will have to close them in stages (as seen in the example video below). 

    4. Click "Tools", then click Bulk Change "all X issues". Select all issues. Click "Transition Issues". 

    5. Transition the issues to the "Closed" state of their workflow. Ensure you set a "Won't Do" resolution. 

    6. Video example:

       

  8. Congratulations! Now you have completed the quarterly graveyard

Related content