Allow tracking issues for multi-step work in JIRA

Development
1

Hello everyone,

Our JIRA rules forbid the Subtask issue type. Currently, this also includes a “no umbrella issues” rule. But, we observed recently that some work does not fit in a single issue (e.g., migrating LT to LD, making the build reproducible, or enforcing required rights). Developers need a way to follow that work, and currently we don’t have a common practice to do so.

In this proposal I’ll try to find a practice that works for all of us.

Current practices

We either use some kind of tracking issue, or create design pages.

  • Tracking issue are basically a bypass of subtask without the integration in Jira (see list below)
  • Design pages are hard to keep in sync, especially are we are not allowed to create ad-hoc labels to track a specific task

Jira tracking issues

Issue Type Linked issues Open since
XWIKI-22666 Moving away from LESSCSS Improvement 6 2024-11
XWIKI-22668 Migrate most of XWiki’s LESS files to native CSS Task 6 2024-11
XWIKI-22847 Make possible to use XWiki without any persistent file storage New Feature 4 (in XWIKI and XCOMMONS) 2025-02
XWIKI-23339 Enforce required rights in all pages in XS Improvement 5 2025-06
XWIKI-24698 Make the XWiki build fully reproducible Improvement 7 (in XWIKI and XCOMMONS) 2026-08
XINFRA-502 Migrate jira.xwiki.org to OpenProject Task 17 Subtasks 2026-10

Design tracking pages

Existing discussions

Mainly Remove JIRA Epic & Story issue types and deprecate usage of the subtask type.
But also:

Vocabulary

“Umbrella issue” is actually an ambiguous term, I suggest using the terms defined below to ease the discussion

  • Subtask: the JIRA issue type that nests an issue under a parent (currently forbidden)
  • Tracking issue: a regular issue whose only purpose is to group linked issues on one topic (I think they should be tasks, and we shouldn’t commit with their ID).

Needs

See bellow a list needs, that can be contradicting:

  • Follow progress of a multi steps tasks (e.g., LD migration)
  • Avoid issues that stay open forever / a list of open issues that means something

Options

A. Keep the rule and clarify it

Still no tracking issues, and we use only design pages to track progress.

Pro:

  • No change, no new risk of open-forever issues.

Con:

  • It does not match what we already do.

B. Allow tracking issues with new closing rules

We keep using regular issues and keep the “depends on” linking mechanism to connect issues together.
In addition, a few more information is required:

  • A done criterion defined by the issue creator (e.g., Building xwiki-commons, xwiki-rendering and xwiki-platform twice, from different directories and as different users, produces identical JARs, WAR, Debian packages and XIP. for a reproducible build work)
  • The assignee is responsible for the respect of the closing rules
  • Optionally, a dedicated tracking label

We follow the closing rules below

  • R1. Normal close. When the done criterion is reached, the issue can be closed with no fix version
  • R2. Leftover steps. If some step issues are still open when the done criterion is met, replace their “depends on” links with “relates to”, in addition to R1.
  • R3. Fixed scope. The done criterion cannot be extended/updated after creation. New issues can only be added if they match the existing definition.
  • R4. Abandon. If after 6 months the issue did not progress, the issue must be closed as won’t fix with no fix version (yes it means closing some existing issues I listed above)

Pro:

  • Allow linking to several projects (sub-tasks can’t do that)
  • Easy to migrate to the parent/child hierarchy of OpenProject.
  • Easy to query (e.g., issueFunction in linkedIssuesOfRecursive("issue = XWIKI-22666", "depends on")).

Con:

  • More rules, needs discipline to apply them well.

C. Allow the Subtask type again

Pro:

  • Natively supported by JIRA
  • Easy to migrate to the parent/child hierarchy of OpenProject

Con:

  • A subtask cannot have Subtasks (e.g., XWIKI-22666)
  • A subtask cannot span several projects

Conclusion

I believe all the proposed option can easily be ported to OpenProject

Here’s my +1 for B.

I’ll align the existing “tracking issues” once a rule is validated. I’m not proposing the exact wording on the new rules to add to the documentation for now to not make the proposal bigger than it already is.

Thanks for reading this far.

2

+1 for B, but I don’t agree with the global “6 months” rule which does not make any sense to me. There is no more reason to close a tracking issue after 6 months of inactivity than any other jira issue, and it’s obviously not because we did not have time to focus on it for the last 6 month that we don’t ever want to do it. As long as there is clear closing criteria and no proposal to decide that the goal expressed by the issue is something we don’t want to do after all, there is no reason to close it.

Things get delayed for various reasons (especially those last months when we were focusing on security):

  • I really doubt anyone will agree on closing XWIKI-22847 as won’t fix
  • It would not make any sense to close as won’t fix issues in charge of tracking things that need to be done before we can apply something which is unavoidable, like XWIKI-22776, or the ones we generally create as soon as one of our dependencies start to requiring a version of Java higher than our minimum supported version. The main reason for those to be inactive for 6 months is generally not so much that we don’t have the time to work on them, but often more than we are not ready to add the constraint they imply (require a higher version of the supported application server, of the minimum supported Java version, etc).

Also, no activity in the linked issues or pull requests does not mean everybody have forgotten those issues and there is no discussion about part of them, just no published progress.

3

+1 with that

4

+1 for B as well with the same objection to the 6 months rule as @tmortagne and @surli.

5

+1, but I find the closing rules too strict: I’m not sure that we need (all of) them.

I don’t agree with this. The fix version should be the version where the done criterion is finally met. From my experience, it’s often the case that the “tracking” issue has commits of its own, to integrate the work done by various dependant issues.

I don’t agree with this. Why so strict? New use cases can be raised or discovered after the issue is created.

Same as Thomas, this doesn’t make sense to me.

Thanks,
Marius

6

I was a bit too focused on R4 in my previous message, but I agree with @mflorea’s comments:

  • R1: it does not make any sense to not indicate in which version that issue was fixed, it’s a very useful information
  • R3: yes, some new problem may be discovered while working on the subject and require new dependency issues
7

Hi @mleduc, thanks for the proposal.

Since we’re about to move to OpenProject (XINFRA-502), I looked at what its parent/child hierarchy supports, because that’s where we’ll end up:

  • Unlimited depth: a child can have its own children (there’s no depth check in the code), so a case like XWIKI-22666 → XWIKI-22668 → … is fine.
  • Across projects: supported once the admin setting “Allow cross-project work package relations” is enabled. That covers the XWIKI + XCOMMONS cases.
  • Progress tracking: the parent shows totals for its children, and there’s a “descendants” filter that lists all levels.
  • Closing: nothing is automatic. The parent can be closed while children are still open, and it doesn’t close when the last child does. So we still need a rule for closing it.

So I think the simplest option is: use plain parent/child, i.e. subtasks in JIRA until we migrate, and native children in OpenProject. In JIRA we can keep the “depends on” approach of B where subtasks don’t fit (several levels or several projects) and convert it to parent/child during the migration.

I’m fine with subtasks, but we need a way to close the parent. I agree with the done criterion of B: the assignee closes the parent when the criterion is met, and any leftover children get moved out (detached or re-parented) so the parent doesn’t stay open forever. Like @tmortagne, @surli and @MichaelHamann, I’m against the 6-month rule (R4). Like @mflorea, I’m against freezing the scope (R3).

I’m -1 for R1 (closing with no fix version). If we allow issues without a fix version, we can no longer tell whether the fix version was forgotten or left empty on purpose. Today we run JIRA filters to find closed issues missing a “Fix Version/s”, and that check only works if every closed issue has one. The parent should get the version in which the done criterion was met.

About the parent having its own commits (@mflorea’s point): I think it shouldn’t. If some work remains to integrate what the children did, we should create a new child issue for it, focused on that remaining work, instead of committing on the parent. A commit referencing the parent is wrong anyway, since it doesn’t implement the whole tracked topic.

To avoid a duplicate entry in the release notes (the parent next to its children), I propose that the parent always uses the “Development Issues only” component. A tracking issue/WP is about coordinating dev work and isn’t meant to be visible to end users: what they care about is in the children. The release notes already exclude that component, so nothing else needs to change.

Thanks

PS: This post was co-written with Claude Code.

8

I don’t agree with this. First, we often do multiple commits per issue so none of them “implements the whole tracked topic” alone, but we still need to mention the issue number. A commit referencing an issue doesn’t imply it implements the entire topic. It never did. It’s just one of the changes needed to implement the topic.

I agree there are cases where a shallow issue used only for tracking makes sense, but from my experience there are plenty of cases where you start working on an issue, and you discover that some parts of it deserve separate sub-issues, like if you need some new API or some new widget. But this still leaves work to be done on your initial issue, to call that API or use that widget. I don’t see what we gain by creating yet another issue in this case.

For me, it’s the opposite: the user is mainly interested in the parent issue. We may be talking about different things though. I guess on my side I didn’t have the need for a technical “tracking” issue. The need I had was to extract some of the work in “child” (sub)issues that block the parent issue. I’ll probably continue to use issue relations for this (depends on / blocks).

Thanks,
Marius

9

Hi, reading the old discussions it’s not clear to me why subtasks were deprecated in the past, but it looks like the parent/child hierarchy of OP does not have technical limitations for us so I’m all for using them. In the meantime, I would be +1 for B, but I also have reservations on the abandon rule.

While we’re at it, I wonder if a system of parent/child issues should not be generalized for large tasks with stakeholders, where the parent’s assignee would be the one that suggested the user story and they would then be responsible for making sure the feature implemented through child issues actually matches the requirements before closing it.

10

+1 for B too, thanks!

About closing, I’m not sure how it would go wrong. I use a very similar process for “Solved By”: when I notice a ticket would probably be fixed by my solution to another ticket, I set a link as “related” to remember it later. When I close any ticket, I take a quick look at links (especially “blocks” and “related to”) and see if there’s anything more to close. For children/parent dependencies it’s the same, checking links when closing would solve most situations.

Note: I migrated the XWIKI-22668 subtask list to the design page since our discussion :slight_smile:

11

Then it’s not a tracking issue. And this whole topic is about tracking issue :slight_smile:

In your case you start with a standard issue and then you realize you also need something else. So you just create that other issue and link them…

Yes, depends/blocks is good for your use case IMO.

Here’s an example of a tracking issue: Loading...

What can be indicated in the Release notes (for large tracking issue closed) is that the last issue concludes the topic of XXX which is now fully implemented. Or something like that.

Thx