Published
Wiki source code of Finish the conversion of the Upgrade documentation into the documentation tree
Last modified by Eleni Cojocariu on 2026/08/13 15:14
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | Finishes the conversion of [[Documentation.AdminGuide.Upgrade>>Documentation.AdminGuide.Upgrade.WebHome]] (revision 49.2 as the source, since later revisions are already partly stripped) into ##documentation.xs.admin.upgrade##, and reviews the 14 pages the topic already had against the Documentation Guide. | ||
| 2 | |||
| 3 | The legacy page was a hub that assembled its "Part 1" from four transcluded pages, so three procedures had never been converted and were still reachable only through it. They are now pages of the new tree, and the legacy tree keeps no documentation of its own. | ||
| 4 | |||
| 5 | **New pages** | ||
| 6 | |||
| 7 | * [[Upgrade XWiki Installed from the Debian Packages>>documentation.xs.admin.upgrade.distribution.upgrade-debian-package.WebHome]] — How-to, converted from the "Upgrading" section of [[Installation using Debian/Ubuntu (.DEB) packages>>Documentation.AdminGuide.Installation.InstallationViaAPT.WebHome]] (the richer of the two sources) merged with ##Documentation.AdminGuide.Upgrade.UpgradeDebian##. Its two troubleshooting notes became FAQ entries. | ||
| 8 | * [[Upgrade the XWiki .war Package>>documentation.xs.admin.upgrade.distribution.upgrade-war-package.WebHome]] — How-to, converted from ##Documentation.AdminGuide.Upgrade.UpgradeWAR##, whose prose was a bullet list of considerations rather than a procedure; it is now ordered steps, with the two considerations that are reader questions ("can I copy on top?", "why the same permanent directory?") moved to the FAQ. | ||
| 9 | * [[Invalid Extensions after an Upgrade>>documentation.xs.admin.upgrade.distribution.upgrade-war-package.invalid-extensions.WebHome]] — Explanation, extracted from the same page, where it was a block inside the procedure. | ||
| 10 | * [[XWiki Startup Failure after a Required Java Upgrade>>documentation.xs.admin.upgrade.troubleshooting.xwiki-startup-failure-java-upgrade.WebHome]] — Explanation with the ##Cause##/##Solution## structure of the other troubleshooting pages, converted from the "XWiki startup failed due to previous errors" section, which was the last piece of prose left on the legacy page. | ||
| 11 | |||
| 12 | **Content corrected against the sources** | ||
| 13 | |||
| 14 | * **The "invalid extension" log sample was 12 years out of date and in the wrong format.** It showed ##org.xwiki.enterprise## artifacts and separated artifact from version with a hyphen; the current message uses a slash, and carries the ##InvalidExtensionException## reason that actually explains the warning. Taken from the assertion in ##Upgrade1011Test## rather than retyped, and the explanation is now the real mechanism (an installed extension pins the versions of its dependencies, so replacing the core extensions invalidates it) instead of "they may have been renamed, removed or have versions that do not match". | ||
| 15 | * **The Java requirement was pinned to an unsupported version.** The legacy text described the Java 17 boundary of XWiki 16.x; per the Java Support Strategy the boundaries that matter now are Java 17 since 16.0.0 and **Java 21 since 18.0.0**, so the page states both and the symlink example targets ##java-21-openjdk-amd64##. | ||
| 16 | * **The Debian package names were stale.** ##xwiki-tomcat9-mariadb## appeared as the example package; the distribution builds ##xwiki-tomcat10-*##, ##xwiki-tomcat11-*## and ##xwiki-xjetty-*## (verified in ##xwiki-platform-distribution-debian##), so the examples use ##tomcat11## and the FAQ gives the naming pattern. | ||
| 17 | * **"Database Upgrade" implied migrations are off by default.** ##xwiki.store.migration=1## is uncommented in the shipped ##xwiki.cfg##; what makes the check worth doing is that it is commonly disabled in production for a faster startup, which is what the page now says. | ||
| 18 | |||
| 19 | **Broken and silently-dropped links** | ||
| 20 | |||
| 21 | * **"Upgrades Troubleshootings" listed its two children as unresolved links** — ##[[XWiki startup hanging during Solr initialization]]## with no target, which renders as a red ##wikicreatelink## to a page that does not exist. Both now link to the pages they name, and the third bullet ("Configuration issues caused by changes in dependencies, servlet containers, or runtime environments") is dropped: it named no page and no symptom. | ||
| 22 | * **"Distribution Upgrades" sent three of its four methods back to the legacy page**, through anchors on a same-wiki link — which xwiki.org drops unless a ##queryString## accompanies them, so the reader landed at the top of the legacy page. All four now point at pages of the new tree. | ||
| 23 | * **Two anchor-only links pointed a page at its own FAQ** and were dropped in the same way: the ##manually merge## link on "Upgrade the Demo Package" now points at [[Unix Merge Configuration Files>>documentation.xs.admin.upgrade.distribution.upgrade-zip-package.unix-merge-config-files.WebHome]], and the last step of the Distribution Wizard page no longer links to its own "Are all the wikis upgraded automatically?" entry. | ||
| 24 | |||
| 25 | **Duplication removed** | ||
| 26 | |||
| 27 | * The FAQ entry **"What if the migration of the database fails?"** was on both "Database Upgrade" and "Upgrade the Demo Package", word for word. It stays on "Database Upgrade", which is the page the other one includes. | ||
| 28 | * The FAQ entry "How to do the merge of the files on Unix operating systems?" existed only to link the merge page that the step now links directly. | ||
| 29 | |||
| 30 | **Documentation Guide fixes on the existing pages** | ||
| 31 | |||
| 32 | * **The three ##WIP## warning banners are gone** (the hub, "Upgrades Troubleshootings", "XWiki Startup Stuck during Solr Initialization" and the Distribution Wizard page), since the topic is now complete. | ||
| 33 | * **A result step closes each How-to.** All five stopped on their last action, so the reader could not tell whether the upgrade had worked. On the Distribution Wizard page the existing report screenshot becomes that step. | ||
| 34 | * **Titles:** "Upgrades Troubleshootings" reads as "Upgrade Troubleshooting"; ##using## is capitalised in the two flavor titles, per English title case. | ||
| 35 | * **Types and audiences:** "Database Upgrade" was targeted at ##user## although it is about editing ##xwiki.cfg## on the server — now ##administrator##; "Upgrade the Flavor Using the Export/Import Method" was typed ##tutorial## although it is a generic procedure with no worked example — now ##howto##. | ||
| 36 | * **The hub did not link two of its children.** "Move XWiki to a New Server and Upgrade it" and the troubleshooting page were reachable only through the automatic "More" table. The hub also had its three recommendations as a numbered list, which is a procedure inside an Explanation, so they are a plain list now. | ||
| 37 | * **"Unix Merge Configuration Files" described commands that were all in one block at the end**, so neither section contained the commands it described. The block is split into the two sections. | ||
| 38 | * Typos: ##permananet## (twice), ##upgarde## (twice), ##limitatations##, ##Distrivution##. | ||
| 39 | |||
| 40 | **The legacy pages** | ||
| 41 | |||
| 42 | ##Documentation.AdminGuide.Upgrade## and its three remaining children (##UpgradeDebian##, ##UpgradeWAR##, ##UpgradeDocker##) keep only a pointer at the new pages. The old section anchors are preserved with the ~{~{id}} macro — ##HDowngrading##, ##HPart2Upgradingtheflavor##, ##HAlternativeStartfresh2CplusExportandReimportyourdata## and the four ##HMethod1.*## ones — because they are what saved links and the release notes use. The "Upgrading" section of the Debian installation page keeps its heading and its ##HUpgrading## anchor and points at the new How-to, rather than leaving the procedure duplicated. None of these pages has any attachment, so there is none to delete. | ||
| 43 | |||
| 44 | Backlinks of the legacy page were triaged rather than rewritten wholesale: the two documentation pages that linked to it for prose reasons are repointed ([[Wikis vs Nested Pages>>documentation.xs.admin.base.content-organization.wikis-nested-pages.WebHome]] and the Related links of [[Installation>>documentation.xs.admin.installation.WebHome]]), while the fifteen ##MyXWiki.org upgraded to …## blog posts, the two release notes and the download-form feedback page are left alone as dated records. | ||
| 45 | |||
| 46 | **Applied outside this change request** | ||
| 47 | |||
| 48 | "Upgrade XWiki Installed in Docker" was **moved** from ##documentation.xs.admin.upgrade## to ##documentation.xs.admin.upgrade.distribution##, so that the four distribution methods are siblings under the hub that lists them. A change request cannot carry a move, so it was done as a rename with "Update links" and an automatic redirect: the old URL still resolves, and the one incoming link (the Related links of "Install XWiki using Docker") was repointed automatically. | ||
| 49 | |||
| 50 | **Known limitation, not fixed here** | ||
| 51 | |||
| 52 | The five screenshots on the Distribution Wizard page are **799 to 803 pixels wide** but are displayed at ##size="large"## (650px) and inside a Gallery, so the browser rescales them. Re-capturing them at the exact width requires running a real flavor upgrade — an instance of an older version upgraded to the current one — which is what the ##flavor-test-upgrade## integration tests set up. They are left as they are, and are worth a follow-up. For the same reason the new pages carry no screenshot: the Debian, ##.war## and Java procedures happen on a terminal, where the code examples are what shows the reader the commands and the messages to look for. |
