This bug workaround will primary benefit larger Jira instances with many Epics.
When creating bugs or feature requests, there is an Epic Link field letting you connect your new issue to an existing Epic.
Have you noticed that is showing rather a lot of Epics in the Epic Link drop-down? In fact, that it is showing Epics that are resolved, despite the Show done epics checkbox being unchecked?
This is because the Epic Status field on those Epics is not in sync with reality. This happens when Epics are resolved through regular Jira issue screen, and not via a Board.
Background
Jira renders closed/resolved issues as striked out links. Closed issues also don't appear in the default "Open Issues" filter or "Created vs Resolved" portlet.
But Jira workflows are arbitrary:
- A Bug may transition from Open → In Progress → Resolved → Closed.
- A Task may go from Todo → In Progress → Done.
- A HR workflow might be Prospect → Interviewing → Hired.
How does Jira know that some statuses ("Closed", "Done", "Hired") mean the issue is finished, and can be rendered striked out?
Answer: it relies on the presence or absence of the resolution field. To Jira, no resolution means 'open'. It's a hack, and leads to problems when workflow designers fail to set/unset resolution in sync with the status, but it works. See https://confluence.atlassian.com/cloudkb/best-practices-on-using-the-resolution-field-968660796.html for discussion.
Then in ~2006 or so along came Greenhopper, a Jira plugin that added Epics and Agile Boards to Jira. Greenhopper also needed a way to identify done Epics, so they could be removed from the Backlog 'Epics' filter, and removed from the 'Epic Link' filter shown above.
For some reason, rather than rely on resolution as a marker, Greenhopper added a new hidden custom field, Epic Status, with hardcoded values To Do , In Progress and Done. This custom field needs to be kept in sync with the Status field on Epics.
Atlassian simply never implemented a way of syncing Epic Status with Status. They put a page in the docs saying how to modify the Epic workflow to achieve it, but nothing more. And thus Jira in the world has Epic Link fields showing Epics that shouldn't be showing, as in the screenshot above.
(Aside: Epic Status was a bad idea anyway, and Atlassian later implemented 'status categories' which achieve the same thing. There is a never-to-be-fixed bug suggesting Epic Status be removed in favour of status categories)
Workaround
There are two parts to our fix:
1) Fix the existing problem
In Jira, if you run the JQL search:
issuetype=Epic and resolution is not empty and "Epic Status" is empty
you should get no results (all resolved Epics should have 'Epic Status' set).
If you get results, you need to click the top-right 'Edit' button in the search results, and bulk edit them to set the Epic Status field to Done.
After this bulk edit, try to create a bug, and find the Epic Link field. It should now correctly show only the really-open Epics.
2) Prevent the problem from recurring
To keep Epic Status in sync with Status one can used the Groovy listener, originally posted by at https://community.atlassian.com/t5/Jira-Software-questions/EPIC-Status-Vs-Status/qaq-p/728237, and replicated here for posterity:
As of (Jira 8.20.x) the code works with no modifications needed except customizing the custom field ID.