What do we backport on a supported branch?

[vmassol]

Hi devs,

Current Situation

I couldn’t find any written doc on xwiki.org about what we’re supposed to backport on supported branches (neither in https://dev.xwiki.org/xwiki/bin/view/Community/VersioningAndReleasePractices/, nor in https://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices, nor in https://www.xwiki.org/xwiki/bin/view/Main/Support#HCommunitySupport).

I’ve even asked chatgpt and the answer was:

Here’s an overview of how XWiki handles decisions about what gets backported to older branches (e.g., stable or LTS branches):

1. General Project Practice

There isn’t a highly formalized, strict backport policy written down, but the Versioning & Release Practices documentation and discussion threads describe the “usual” expectations:

• XWiki maintains stable branches (e.g., stable-<version>.x) and LTS branches for past major releases. (dev.xwiki.org)
• When an important bug is fixed on master, it is usually backported to these older branches so that they benefit from critical fixes. This happens “when it’s needed”, which can be:
  • When a critical/important bug is found in an older branch.
  • When people request it (e.g., users or committers asking for a backport).
  • When the committers deem there are “enough fixes” to justify a backport. (dev.xwiki.org)

There isn’t a checklist of mandatory categories beyond that — it’s a pragmatic, case-by-case choice. (dev.xwiki.org)

---

2. Types of Changes Commonly Backported

In practice, backports to older branches tend to include:

• Bug fixes (especially important or high-impact ones).
• Security fixes — these are prioritized to all supported branches as part of the security policy (critical and blocker issues are to be fixed on all supported branches within a defined timeframe). (dev.xwiki.org)
• Occasionally feature improvements that are considered safe, usable and valuable for the older branch — but these are usually discussed explicitly among developers (often via forum votes) before backporting. (XWiki Forum)

Less commonly, more subjective or larger changes (especially if they might risk regressions) are debated or deferred.

---

3. Decision Process

The decision whether to backport something usually happens in one of these ways:

A. Informal Developer Discretion

Many committers exercise discretion based on the branch’s support status and the perceived importance of the fix — especially for stable (non-LTS) branches. (dev.xwiki.org)

B. Discussion and Votes on the Community Forum

For improvements that are not clear cut (e.g., non-trivial features or enhancements), developers will often:

1. Open a thread on the XWiki forum proposing to backport a specific change. (XWiki Forum)
2. Discuss safety/impact of the change, with other committers and interested contributors giving feedback. (XWiki Forum)
3. Sometimes vote explicitly (e.g., +1/+0/-0) on whether it should be backported. (XWiki Forum)
4. Decisions are then recorded and the backport is applied if there’s consensus (or sufficient support).

This democratic discussion process is common on medium-risk or “feature-adjacent” backports, like improving macro behavior in an LTS branch. (XWiki Forum)

---

4. Automated or Label-Guided Backporting

XWiki has experimented with automation around backports:

• Some repositories use a label (e.g., backport stable-xxx) which, when applied to a pull request, indicates that the change should be automatically backported to the corresponding stable branch. (XWiki Forum)
• This helps reduce mistakes and ensures backports aren’t forgotten across multiple modules/repositories. (XWiki Forum)

---

5. Branch Support Scope Influences Backport Decisions

Two practical things that influence what gets backported:

• Only supported branches (current LTS + current stable) are routinely considered. Other older branches might still get backports if a committer personally maintains them, but such activity isn’t considered official project support. (XWiki Forum)
• During LTS transitions (e.g., when a new LTS is released), committers may evaluate whether to backport important issues to the previous LTS before dropping it — though exact policies on this are sometimes discussed on the forum rather than formally mandated. (XWiki Forum)

---

Summary

Aspect	Typical Handling
Who decides	Committers discuss and decide; sometimes a forum vote
What gets backported	Critical bug fixes, security fixes, and safe/valuable improvements
How	Case-by-case or label/tag assisted; community forum discussion
Formality	Not a strict checklist — more flexible and pragmatic

---

If you want exact current guidelines for your specific branch/version, another good source is the Versioning & Release Practices page on the XWiki wiki (which lays out supported branches, release cycles, and general philosophy). (dev.xwiki.org)

Would you like a link to that documentation or examples of forum threads where backport decisions were discussed?

It confirms that we don’t have a precise written doc on that, so here’s a proposal.

Proposal

Note that our supported branches are bugfix branches. I don’t think we have other types of branches.

• Must: Backport only bug issues.
• Must: Backport Blocker level bug issues. Note that this includes important security issues, since they’re mapped as blocker bugs as per our Security Policy.
• May: Backport bugs with a priority < Blocker, at the discretion of the developers.
• May: If a developer thinks a non-bug issue should be backported, a forum proposal or vote must be sent to make sure stability concerns are addressed and that other developers agree. Note that this point is especially important when a developer needs to finish a feature started in the current cycle and the N.10.0 version has already been released (i.e. he/she’s late) and without the proposed changes, the feature wouldn’t be considered as finished or usable-enough by the stakeholders of that feature.

WDYT? Have I missed anything?

When agreed, I’ll update the documentation on dev.xwiki.org.

Thanks

[tmortagne]

@vmassol

Must: Backport only bug issues.

We currently also backport some dependencies which are related to the build (mainly test related dependencies like testcontainers and selenium, as well as their required transitive dependencies, but only in the current LTS) or the environment (database connectors). I don’t think it’s a good idea to stop doing that.

[surli]

@vmassol

• Must: Backport only bug issues.
• Must: Backport Blocker level bug issues. Note that this includes important security issues, since they’re mapped as blocker bugs as per our Security Policy.
• May: Backport bugs with a priority < Blocker, at the discretion of the developers.
• May: If a developer thinks a non-bug issue should be backported, a forum proposal or vote must be sent to make sure stability concerns are addressed and that other developers agree. Note that this point is especially important when a developer needs to finish a feature started in the current cycle and the N.10.0 version has already been released (i.e. he/she’s late) and without the proposed changes, the feature wouldn’t be considered as finished or usable-enough by the stakeholders of that feature.

+1 but as Thomas mentioned I would also mention specific dependency upgrades (those solving security issues or needed for the build or to solve blocker bugs)

[vmassol]

@tmortagne

We currently also backport some dependencies which are related to the build (mainly test related dependencies like testcontainers and selenium, as well as their required transitive dependencies, but only in the current LTS) or the environment (database connectors). I don’t think it’s a good idea to stop doing that.

yes if it’s test-only and doesn’t go in the distribution, there’s no problem doing that. I’ll add it. Thx

[vmassol]

@surli

as Thomas mentioned I would also mention specific dependency upgrades (those solving security issues or needed for the build or to solve blocker bugs)

Thomas only mentioned test deps.

Adding an explanation for the other deps (they were included for me but it’s better to be explicit).

[vmassol]

Updated proposal:

• Must: Backport only bug issues.
• Must: Backport Blocker level bug issues. Note that this includes important security issues, since they’re mapped as blocker bugs as per our Security Policy.
• May: Backport bugs with a priority < Blocker, at the discretion of the developers.
• May: If a developer thinks a non-bug issue should be backported, a forum proposal or vote must be sent to make sure stability concerns are addressed and that other developers agree.
  • This is especially important when a developer needs to finish a feature started in the current cycle and the N.10.0 version has already been released (i.e. he/she’s late) and without the proposed changes, the feature wouldn’t be considered as finished or usable-enough by the stakeholders of that feature.
  • A forum proposal or vote is not needed in the following cases:
    • The issue is a dependency upgrade that doesn’t go in the distribution (test or build dependency)
    • The issue is an upgrade that is required to fix a bug that is being backported.

[tmortagne]

@vmassol

yes if it’s test-only and doesn’t go in the distribution, there’s no problem doing that

As I mentioned, there is also transitive dependencies of those build tools, and those often go in the distribution (mainly Apache Commons stuff, but also docker which we are using at runtime too). And connectors do go in the distribution (at least postgres and mysql/mariadb), even if not in the WAR.

[vmassol]

@tmortagne

As I mentioned, there is also transitive dependencies of those build tools, and those often go in the distribution (mainly Apache Commons stuff, but also docker which we are using at runtime too).

Then I disagree that they should be backported without asking. For me this goes in:

May: If a developer thinks a non-bug issue should be backported, a forum proposal or vote must be sent to make sure stability concerns are addressed and that other developers agree.

@tmortagne

And connectors do go in the distribution (at least postgres and mysql/mariadb), even if not in the WAR.

This is potentially dangerous. I’ve seen regular problems with JDBC driver upgrades (including a recent one). I don’t think they should be blindly backported in a bugfix branch and I believe they also require a discussion. The best for them would be to have enough feedback for their upgrade on the main branch first, before deciding to backport. In any case, I would put it in the “ask” category.

WDYT?

Thx

[tmortagne]

To me, it does not make much sense to require a forum post to upgrade an Apache Commons dependency. They have very strict retro compatibility rules.

It’s not the case of dockerJava, but at the same time I highly doubt a regression in dockerJava would go unnoticed by the build.

@vmassol

I’ve seen regular problems with JDBC driver upgrades

I don’t think so, no. Maybe a few times in the last 15 years. Not to mention that we recommend in the documentation to use the latest JDBC connector, for LTS too, in the case of manual installations.

@vmassol

including a recent one

That one was actually upgraded because of a CVE. So it would have been anyway according to the rules you proposed.

[vmassol]

@tmortagne

I don’t think so, no. Maybe a few times in the last 15 years. Not to mention that we recommend in the documentation to use the latest JDBC connector, for LTS too, in the case of manual installations.

The recent one I had in mind was Loading...

[tmortagne]

@vmassol

The recent one I had in mind was Loading…

And as I mentioned, this one was also upgraded because of a CVE (which might be linked to the regression, if they had to change some behavior to fix the security vulnerability).