Best practices for linking Jira issues
- Brent Emerson
- Karenna Wait
- Michele Bromley
One of the important benefits we get from using a work tracking system like Jira is being able to record, visualize, and communicate the relationships between different pieces of work. To show these relationships, we can link issues to each other (using one of seven different link types), or we can connect them with a containment relationship. This brief guide suggests best practices and shared meanings for various link types and containment structures, as they are used at PSU.
Link types
Link type (and its reverse) | Suggested use / Definition | Commentary / Examples |
|---|---|---|
blocks (is blocked by) | Issue A blocks issue B if work cannot proceed on B without resolving A. | Is blocked by and depends on are very similar relationships. In addition to having a more negative feeling, A is blocked by B implies that work on A is completely stopped until B is resolved. A depends on B just means that B will have to happen before A finishes; work may be ongoing on both and may happen in parallel. |
causes (is caused by) | Problem A causes Incident B if A has been identified as the root cause of B. | Should only be used to link incidents (either explicit Incident issues or other types of issues reporting service interruptions) to Anchor Incidents or OIT Alerts or to the Problem issues agents create to do root cause analysis. |
clones (is cloned by) | Issue A clones issue B if A was created from B by Jira's "clone" action. | Should only be used on issues that are created by cloning (and in this case the link will be auto-created, so manual action with this link type is rare). |
depends on (is depended on by) | Issue A depends on issue B if A can't be completed until B is complete. | We may be working on both at the same time (or not), but in the end, we'll need to wait for B before A can be resolved. B might involve building something that A needs, or testing something, or making a decision, or any number of other things. Note: nothing in the system actually prevents A from being closed prior to B. |
derived from (derives) | Issue A is derived from issue B if something about B (its mere existence, or things we discovered in working on it, or its resolution) suggests that we should do the separate but related work described in A. | When this link type is used, A was usually created after B, as a consequence or a next step or a continuation. |
duplicates (is duplicated by) | Issue A duplicates issue B if A represents exactly the same work as B. | This link type is usually used when a duplicate issue is inadvertently created, and may explain why A was resolved before the work it represents was actually completed. |
relates to (relates to) | Issue A relates to issue B if A has any relationship at all to B. | This is a good catch-all/default link type. It is often used when the more specific link types above don't apply, or when two issues have no logical or causal or temporal hierarchy; they're just related in sort of a flat or equal way. All other link types have hierarchy/directionality; this one does not. |
Another kind of issue relationship: containment
Issue links (above) show relationships between separate but related work. Another type of relationship pattern occurs when one project or initiative is made up of a bunch of tasks. The project doesn't exactly depend on the tasks; the tasks constitute the project, and when they're all complete, the project is complete. The tasks are contained by the project.
It would be nice if we could define infinite levels of containment (for instance, Strategic Priorities contain Initiatives, which contain Big Projects, which contain Small Projects, which contain Tasks, which contain Subtasks, which contain Microtasks) but Jira offers only a few levels of containment.
The main containment relationship is: Epics contain Tasks (or other kinds of issues). Epics are usually created to define a project, large or small, to organize the work that constitutes the project and track its progress. When all contained issues are resolved, there's generally no work left to do to complete the project. Epics are frequently used to organize projects undertaken by a single team, and also to organize projects whose tasks are shared across several teams. Note one practical limitation to this kind of containment: Epics in a next-gen project can only contain issues in that project.
A similar pattern can be modeled at a lower level: Tasks contain Subtasks (aka Child issues). In theory this can have exactly the same meaning as the Epic structure, except the scale of work is much smaller. In practice, the Task also commonly contains some work of its own, with Subtasks expressing the largest chunks, or places where one agent or team needs to delegate some work to another. Again, as a practical matter, note that subtasks have to be in the same project as their parent tasks.