Allow tracking issues for multi-step work in JIRA

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.

+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.

+1 with that

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

+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

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

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.

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

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.

+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:

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

Hello all,

Thanks for the numerous feedback. Option B has everyone’s support, see below a revised version.

Refinements

  • R4 (abandon after 6 months) is removed. No arbitrary closing condition
  • R3 (fixed scope) is removed. The scope can grow when we discover new problems. The assignee then updates the done criterion in the description, keeping it up to date.
  • R1 is fixed. A tracking issue closes as Fixed with the version in which the done criterion is met. Every closed issue keeps a fix version, so the filters for missing fix versions keep working.
  • R2 is refined. When the done criterion is met, each step issue still open either gets “relates to” instead of “depends on”, or moves under another tracking issue.

Tracking issues and commits

[quote=“vmassol, post:11, topic:19006”]
Then it’s not a tracking issue.
[/quote]

I agree with @vmassol here. I find it better if a tracking issue gets no commits. @mflorea, the case you describe can be solved by creating a dedicated sub-issue for the glue work that requires a commit.

Release notes

As @vmassol proposes, tracking issues use the “Development Issues only” component, and consequently as not displayed in release notes.
Though this does not prevent adding a release change explaining that the ongoing work is now done.

Labels and the OpenProject (OP) migration

I suggest maing the tracking label mandatory to ease the OP migration. In JIRA we keep “depends on” as the only linking convention, and no Subtasks. During the migration, the “depends on” links of tracking issues become parent/child relations.

Design pages

I propose to not make the existence a design page mandatory.
I suggest encouraging their creation to keep the reasoning and decisions, and shows the status with a JIRA macro query instead of a hand-maintained list. For instance with:

issue in linkedIssues("XWIKI-22666", "depends on")

Existing issues

I propose to align the existing tracking issues collectively, on a best-effort basis, whenever we touch them: label, Task type, component, done criterion and link direction.

Generalizing parent/child

@pjeanjean, using parent/child for stakeholder-driven features sounds like a good idea, but it goes beyond tracking issues. I suggest starting a new dedicated discussion.

Proposed changes to the JIRA rules

In Choose the right issue type, replace the Subtask note with:

  • Subtask: Must not be used. Use a tracking issue instead (see below). We need to remove this type but it’s hard to do now as lots of issues were created as subtasks in the past.

Add a new rule:

== Rule: Use tracking issues for multi-step work ==
A tracking issue groups the issues needed to reach a multi-steps goal(e.g., making the build reproducible, moving away from LESS, or migrating all livetables to Live Data).

  • Use the Task type, the tracking label and the “Development Issues only” component.
  • Write a done criterion in the description. Update it when the scope changes.
  • Set an assignee, who is responsible for closing it.
  • Link it to each step issue with “depends on”. A step issue can itself be a tracking issue.
  • Never commit on a tracking issue. If work remains, create a step issue for it.
  • When the done criterion is met, close it as Fixed, with the version in which the criterion was met. If needed, each step issue still open at that time gets a “relates to” link instead of “depends on”, or moves under another tracking issue.

In Use the right labels, add:

  • tracking: for tracking issues (with a link to the rule above)

Next step

Since everyone voted +1 for B, I’m waiting a few days before updating the rules as proposed above.

Thanks

err no, I think I was more pushing for C actually (but with special rules for closing the parent tracking issues). And ofc to keep the “depends on” relationship when there’s no need for a dedicated tracking issue.

I really see no advantage of not using parent/child issues when there’s a tracking issue need. The issue we had with not using parent/child issues in the past was about closing them but if we agree with the rule defined for that (the ones from your last post) then I only see positives things for parent/child (better UI, made for that, etc).

The other option is to not do that now and only start using parent/child issues after we make the move to OP, but not sure why we should wait. See below for why it’s best to do it sooner than later.

That seems too complex to me. If an issue depends on another one then it’ll migrated the same way (using relationships). And if an issue is a task with subtasks they’ll also be migrated fine. That makes it much simpler and otherwise it’s not supported by the jira migrator.

It’s not easy to make any change once an issue has been imported in OP for various reasons:

  • If we have to recreate the issue then it gets a different id, breaking the URL redirections
  • If we bring some changes to past issues, then the last modified dates change and they’re not longer similar with jira).

Thus imported issues should not be touched as much as possible (it’s possible to use some Ruby on Rails console to perform changes and bypass the UI but it’s not the most easy and we should try to avoid that).

Thanks

Fine with me as long as we accept to have two shapes of tracking issues:

  • Sub-tasks when possible (all the sub-tasks are from the same project)
  • tracking label + “depends on” links otherwise (e.g., XWIKI-22847 or XWIKI-24698, which have steps in XCOMMONS)

The rest of the rules wouldn’t change.

@vmassol one question: would this special case make the migration to OpenProject more difficult?

I wouldn’t even use the tracking label. The issue will be “Development Only” and task, that’s clear enough IMO and we won’t migrate it to parent/child.

No. The jira importer can import parent/child issues and normal issues with relations.

Thx