Description

• Context
• Goals
• Main decisions
  • Scope and cutover
  • Data mapping
  • Security issues
  • Linking commits
  • Pages on xwiki.org
  • Tooling and processes
• Plan
  • Checks for each import
• Progress
• Also needed from OpenProject

Context

jira.xwiki.org runs a self-hosted Jira Server version that no longer receives updates, and upgrading is not possible since Atlassian ended its server offering. Keeping an unmaintained, publicly reachable tool is a security risk, so we need to move away from it as soon as possible.

The community chose OpenProject as the replacement (see the forum discussion, the alternatives considered and the requirements evaluation). https://op.xwiki.org already hosts some contrib projects. This page describes how we migrate all the remaining projects and switch Jira off.

How we use OpenProject (conventions, fields, statuses, workarounds) is documented on the OpenProject usage page, which is updated as decisions are agreed.

Goals

• Move every Jira project to OpenProject: XWiki Standard projects (XCOMMONS, XRENDERING, XWIKI), contrib projects and retired projects.
• Keep issue keys: XWIKI-12345 stays XWIKI-12345 in OpenProject and new issues continue the same numbering. Commit message conventions don't change, and existing references (commits, release notes, advisories, forum posts) stay valid.
• Keep every jira.xwiki.org/browse/KEY link working through permanent redirects to OpenProject.
• Make jira.xwiki.org read-only and no longer publicly reachable right after the last project is migrated, then switch it off after a 3-month safety period used to recover anything the migration missed.
• Keep the pages on xwiki.org that display issues working, using OpenProject equivalents.

Main decisions

Scope and cutover

• All Jira projects are imported, including retired ones (placed in an "Archived" container in OpenProject). OpenProject becomes the archive of our issue history.
• Projects move in waves: contrib projects first, which lets us practice the migration on smaller projects, then XCOMMONS, XRENDERING and XWIKI together on a single weekend, after at least one full dry run.
• Each cutover is a freeze-and-switch: the Jira project is made read-only, imported, checked automatically, then opened in OpenProject and its /browse/KEY URLs are redirected. There is no synchronization between the two tools.

Data mapping

• Jira components become OpenProject categories. Since a Jira issue can have several components, the XS projects are imported once OpenProject supports multiple categories per work package (an announced OpenProject change); otherwise the extra components are kept as labels and converted later.
• XCOMMONS, XRENDERING and XWIKI are always released together, so their versions become shared versions defined once on the "XWiki Standard Projects" container. Contrib projects keep their own versions.
• Resolutions are folded into statuses (Fixed, Won't Fix, Duplicate, Solved By, Cannot Reproduce, Invalid, plus a new Inactive status used by Bug Fixing Days). "Done" becomes Fixed and "Incomplete" becomes Invalid.
• Priorities: Blocker and Critical are unchanged, Major becomes Normal, Minor and Trivial become Low.
• Types: Idea becomes New Feature (with an idea label), sub-tasks become child work packages of their parent.
• Users who appear in Jira data are created in OpenProject (matched by email) without being notified; they activate their account when they want to use it. Logging into OpenProject with an xwiki.org account is a possible later improvement.

Security issues

Security issues are reported and followed in the XS projects today, using Jira's "Confidential" security level. OpenProject doesn't support confidential work packages yet, so they're the one thing that can't move as is.

• Preferred: keep security issues in our tracker, using confidential work packages and private reporting in OpenProject: a report visible only to its reporter and the security team, private by default, made public at disclosure. Issues still confidential in Jira are then imported as confidential work packages. We're asking the OpenProject team what the feature will cover and when it will be available.
• Plan B, prepared so that we're ready: if the feature doesn't cover our needs or doesn't arrive in time for the XS migration, vulnerabilities are reported through GitHub private vulnerability reporting (or security AT xwiki.org) and handled in GitHub Security Advisory drafts, with a neutral public placeholder work package carrying the key, assignee and Fix Versions. Issues still confidential in Jira are copied into advisory drafts, and their keys are kept valid by placeholders. It's more complex (two items to keep in sync per issue, reports split across repositories) and lacks tracker features (assignee, status, versions, search), so it also needs tracking added to the Security Advisory Application, and the advisory discussion (reproduction steps, technical details) copied to the placeholder some time after publication, so that it eventually becomes public as with Jira today. See the forum brainstorming.
• Alternative considered: a private subproject per project, suggested by the OpenProject team. Reports still come by email or GitHub private reporting, since non-members can't create work packages in a private project. Each project receiving security issues gets a private subproject whose only member is a "Security" group, with the parent's versions shared to it for the Fix Versions. A security issue is one work package there, followed by its reporter through work package sharing, and moved to the public project at disclosure with its history (internal comments stay private, and the old key stays as an alias). Issues still confidential in Jira are imported with the project, which the migrator always creates private, then moved to the subproject before the project is made public. It's better than plan B at tracking, but heavier: commits carry the subproject's key prefix before disclosure, which shows which commits are security fixes; subprojects don't inherit categories, types and custom fields, which means many private projects to maintain with the contrib projects; GitHub Security Advisories are still needed for the advisory, the CVE and the private fork; and making a project public before its confidential issues are moved out discloses them. It's kept as an alternative, not as plan B. See the forum discussion and REQM25 in the OpenProject requirements.

The choice gets its own proposal and vote on the forum, once the OpenProject team has answered. We'll choose one or the other and not switch twice (Jira, then GitHub, then OpenProject).

Contrib projects move before the XS projects, possibly before that choice. A contrib project with confidential issues still in Jira moves with the XS projects, and is handled like them. For contrib projects that have already moved, new security reports go to security AT xwiki.org and are handled in a GitHub Security Advisory draft on the project's repository until the choice is made; the public work package is created when the fix is committed.

Linking commits

GitHub autolinks turn issue keys into links to OpenProject. Since OpenProject only links pull requests, a small bot links pushed commits to the work packages mentioned in their message, which also lets the Release Plan list unresolved issues that already have commits. We'll request native support from OpenProject, and the bot can be removed once it's available.

Pages on xwiki.org

A survey of all xwiki.org wikis found about 23,200 Jira macro calls on about 3,800 pages, plus about 1,100 hard-coded links to Jira searches. No Jira chart or count macro is used outside its own documentation, and no advanced JQL (functions, history operators) is used. The pages produce new content after every release, so each kind of usage gets an OpenProject equivalent and existing pages are converted by script:

Historical queries that cannot be translated simply (e.g. very old release notes using OR conditions) may be replaced by a static list. This requires a few improvements to the OpenProject macros: anonymous read access to public projects (with caching), list and inline display styles, referencing work packages by key, and displaying versions, categories, labels and custom fields.

Tooling and processes

• Release: the Maven release currently creates and releases Jira versions automatically; a replacement doing the same in OpenProject is added to the parent POM. Meanwhile, migrated projects release with -Dxwiki.release.jira.skip=true.
• CI: the detection of known flickering tests queries OpenProject instead of Jira.
• notifications AT xwiki.org keeps receiving issue changes through a dedicated OpenProject account.
• New contrib projects are created from an OpenProject template project.
• Development process pages (issue tracker usage, release process, release plan template, contributing, committership, security policy) are updated as each wave lands.
• Shipped XWiki versions keep their links to jira.xwiki.org, which the redirects cover; the links are updated in the next release.

Plan

The schedule depends on the readiness of the OpenProject Jira migrator, with two milestones:

• T0: the migrator can import our contrib projects. It needs official support for our Jira version, keeping confidential issues and restricted comments out of the import, and project keys longer than 10 characters (or we rename those keys first).
• XS-ready: what XCOMMONS, XRENDERING and XWIKI need on top of that: resolutions and resolution dates, issue links and sub-tasks, labels, multiple categories per work package, reliable imports at the scale of XWIKI (about 23,700 issues), inline images and issue links in descriptions, and confidential work packages (see "Security issues", unless we go with plan B).

We prefer these in the migrator. Fixing data after the import through the OpenProject API would reset the "updated" date of most issues, so scripts are a last resort, ideally run on the server.

All dates below are relative to T0.

We want to complete the migration ASAP. Contrib projects can move soon after T0; the XS migration, and therefore the end of the public Jira, waits for XS-ready.

Checks for each import

A first test import of a small contrib project (10 issues) was done on 2026-10-16. Token authentication works with our Jira version, and keys, dates, comments, attachments, versions and custom field values are kept. History is kept as text entries by a "System" user, and the creation entry already shows the final values.

Every test import and dry run is checked against this list (each item until the migrator handles it):

• Inline images are displayed, including those whose name contains spaces (e.g. screenshots), which are left as Jira markup today; links to attachments work. Attachment names have their spaces replaced by underscores.
• Resolution and resolution date.
• Labels.
• Issue links, including to issues of other projects (which need those projects imported in the same run, or a second pass), and sub-tasks.
• Components become categories.
• History: who made each change and when, and whether the initial state of the issue is visible.
• Watchers: Jira watchers are imported and no extra ones are added.
• Comment edit dates, and issue keys in text turned into links.
• Restricted comments and confidential issues are absent.
• Project memberships, project visibility and parent project.

Progress

• The work is tracked in XINFRA-502, with one sub-task per workstream (test import, OpenProject configuration, macro improvements, conversion scripts, commit linking, release plugin, redirects, CI, documentation, each migration wave, Jira shutdown). XINFRA keeps its keys when it moves to OpenProject with the contrib projects, so the tracking carries on there.
• Each milestone (OpenProject's answers, T0, each contrib batch, the XS migration, Jira read-only, Jira switched off) is announced as a reply in the forum proposal.

Also needed from OpenProject

Besides the migrator needs listed in the plan, we need these features too. They don't block the migration only because each has a temporary workaround (described above). The workarounds are suboptimal, so we'll remove each one as soon as OpenProject provides the feature:

• Linking pushed commits, not only pull requests.
• Hiding built-in fields (e.g. versions) per project, for projects that don't use them.
• OR conditions in work package filters.
• Filtering work packages by their key.
• Detecting duplicates when creating a work package.
• Charts over time (created vs resolved, open issues over time).
• A Jira-compatible query layer (#79248): the existing xwiki.org pages would keep working on the day of the switch and could be converted afterwards, instead of all before the XS migration.