Skip to Content
Last modified by Agnease on 2026/05/26 10:58
From version 1.5
edited by Agnease
on 2026/05/12 14:48
Change comment: There is no comment for this version
To version 6.1
edited by Agnease
on 2026/05/22 06:11
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +why-upgrade-xwiki
Content
... ... @@ -1,174 +1,167 @@
1 -/* ========== Resource / Article Pages ========== */
1 +{{velocity}}
2 +#set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
3 +{{html clean="false"}}
2 2  
3 -.resource-page {
4 - padding-top: 34px;
5 -}
5 + <section class="resource-header" aria-labelledby="hero-title">
6 + <div class="container">
7 + <div class="text-center">
8 + <div class="hero-kicker">
9 + <i class="fa fa-refresh" aria-hidden="true"></i>
10 + XWiki upgrade guidance
11 + </div>
12 + </div>
6 6  
7 -.resource-header {
8 - padding: 40px 0 30px;
9 - border-top: none;
10 - background:
11 - radial-gradient(42rem 14rem at 50% 0%, @brand-bg 0%, transparent 70%);
14 + <h1 id="hero-title">Why upgrading your XWiki instance should be a regular priority</h1>
12 12  
13 - .resource-kicker {
14 - display: inline-flex;
15 - align-items: center;
16 - gap: 8px;
17 - color: @brand;
18 - background: fade(@brand, 8%);
19 - border: 1px solid fade(@brand, 18%);
20 - border-radius: 999px;
21 - padding: 6px 12px;
22 - margin-bottom: 14px;
23 - font-size: 13px;
24 - font-weight: 700;
25 - }
16 + <p class="resource-summary">
17 + A working XWiki instance can still become outdated, harder to maintain and exposed to avoidable risks
18 + when upgrades are postponed for too long.
19 + </p>
20 + </div>
21 + </section>
26 26  
27 - h1 {
28 - max-width: 820px;
29 - margin: 0 auto 14px;
30 - text-align: center;
31 - line-height: 1.18;
32 - }
23 + <section class="resource-page">
24 + <div class="container">
25 + <div class="resource-layout">
33 33  
34 - .resource-summary {
35 - max-width: 780px;
36 - margin: 0 auto;
37 - color: @muted;
38 - text-align: center;
39 - font-size: 18px;
40 - line-height: 1.55;
41 - }
42 -}
27 + <aside class="resource-sidebar" aria-label="Page summary">
28 + <h4>In this guide</h4>
29 + <ul>
30 + <li><a href="#why-it-matters">Why upgrades matter</a></li>
31 + <li><a href="#upgrade-checklist">Upgrade checklist</a></li>
32 + <li><a href="#safe-process">Safe process</a></li>
33 + <li><a href="#common-mistakes">Common mistakes</a></li>
34 + <li><a href="#upgrade-rhythm">Upgrade rhythm</a></li>
35 + </ul>
36 + </aside>
43 43  
44 -.resource-layout {
45 - display: grid;
46 - grid-template-columns: minmax(0, 760px) 280px;
47 - gap: 42px;
48 - max-width: 1080px;
49 - margin: 0 auto;
50 - align-items: start;
51 -}
38 + <article class="resource-content">
52 52  
53 -.resource-content {
54 - color: @text;
55 - font-size: 16px;
56 - line-height: 1.68;
40 + <p>
41 + Many XWiki instances continue to run for years with only small visible problems. This can create the
42 + impression that upgrades are optional, especially when users can still log in, search, edit pages and
43 + access the content they need.
44 + </p>
57 57  
58 - h2 {
59 - text-align: left;
60 - margin: 34px 0 12px;
61 - line-height: 1.28;
62 - }
46 + <p>
47 + The real risk is that technical debt accumulates quietly. Security fixes, extension compatibility,
48 + authentication behavior, infrastructure requirements and custom code assumptions continue to evolve.
49 + The longer an instance remains behind, the more difficult the next upgrade becomes.
50 + </p>
63 63  
64 - h3 {
65 - margin: 24px 0 8px;
66 - line-height: 1.3;
67 - }
52 + <div class="resource-note">
53 + <p>
54 + <strong>The main point:</strong> regular upgrades are not only about new features. They reduce security
55 + exposure, compatibility risk and long-term maintenance cost.
56 + </p>
57 + </div>
68 68  
69 - p {
70 - margin: 0 0 16px;
71 - }
59 + <h2 id="why-it-matters">Why regular XWiki upgrades matter</h2>
72 72  
73 - ul,
74 - ol {
75 - margin: 0 0 18px;
76 - padding-left: 22px;
77 - }
61 + <h3>1. Security fixes accumulate over time</h3>
62 + <p>
63 + Older versions may miss security-related fixes already available in newer releases. Once security issues
64 + become publicly known, running an old version can become a more predictable risk.
65 + </p>
78 78  
79 - li {
80 - margin: 6px 0;
81 - }
67 + <p>
68 + This does not mean every old instance is immediately exposed in the same way. The real impact depends on
69 + your configuration, installed extensions, access model, authentication setup and whether the instance is
70 + public or private. But staying close to supported versions makes security maintenance more manageable.
71 + </p>
82 82  
83 - strong {
84 - color: @text;
85 - }
86 -}
73 + <h3>2. Large upgrade gaps are harder to control</h3>
74 + <p>
75 + A small, regular upgrade is usually easier to validate than a large jump after several years. Large gaps
76 + mean more release notes, more compatibility changes, more extension checks and more uncertainty around
77 + custom code.
78 + </p>
87 87  
88 -.resource-note {
89 - border-left: 4px solid @brand;
90 - background: @brand-bg;
91 - padding: 16px 18px;
92 - margin: 22px 0;
93 - border-radius: 0 @radius @radius 0;
80 + <h3>3. Extensions and customizations can become fragile</h3>
81 + <p>
82 + XWiki instances often include installed extensions, custom Velocity scripts, macros, templates, sheets,
83 + UI extensions, Java components or business-specific applications. These elements need to be reviewed when
84 + planning an upgrade.
85 + </p>
94 94  
95 - p:last-child {
96 - margin-bottom: 0;
97 - }
98 -}
87 + <h3>4. Infrastructure requirements evolve</h3>
88 + <p>
89 + XWiki upgrades can involve more than the application itself. Java, Tomcat, the database, Docker images,
90 + reverse proxy configuration, PDF export services and authentication integrations may also need attention.
91 + </p>
99 99  
100 -.resource-checklist {
101 - margin: 18px 0 24px;
102 - padding: 0;
103 - list-style: none;
93 + <h3>5. Business-critical features need validation</h3>
94 + <p>
95 + A successful upgrade is not only one where the server starts. Users usually depend on login, permissions,
96 + search, dashboards, PDF exports, workflows, notifications, custom applications and important pages. These
97 + should be part of the validation plan.
98 + </p>
104 104  
105 - li {
106 - position: relative;
107 - padding: 10px 0 10px 34px;
108 - border-bottom: 1px solid @line;
100 + <h2 id="upgrade-checklist">Practical checklist before planning an upgrade</h2>
109 109  
110 - &:before {
111 - content: "\f00c";
112 - font-family: FontAwesome;
113 - position: absolute;
114 - left: 0;
115 - top: 11px;
116 - color: @brand;
117 - }
118 - }
119 -}
102 + <ul class="resource-checklist">
103 + <li>Identify the current XWiki version and the target version.</li>
104 + <li>Check whether intermediate upgrade steps are needed.</li>
105 + <li>List installed extensions and verify compatibility with the target version.</li>
106 + <li>Identify custom code: Velocity scripts, macros, sheets, templates, UI extensions and Java components.</li>
107 + <li>Review authentication: LDAP, Active Directory, SSO, OIDC, SAML or MFA.</li>
108 + <li>Prepare a staging environment or temporary clone of production.</li>
109 + <li>Validate backups and clarify rollback expectations.</li>
110 + <li>Test important pages, dashboards, permissions, search, jobs, exports and custom workflows.</li>
111 + <li>Document the steps, issues found and follow-up recommendations.</li>
112 + </ul>
120 120  
121 -.resource-sidebar {
122 - position: sticky;
123 - top: 96px;
124 - border: 1px solid @line;
125 - border-radius: @radius;
126 - padding: 18px;
127 - background: #fff;
128 - box-shadow: @shadow-sm;
114 + <h2 id="safe-process">A safer upgrade process</h2>
129 129  
130 - h4 {
131 - margin: 0 0 10px;
132 - }
116 + <p>
117 + Production should not be the first place where the upgrade is tested. The safest approach is to rehearse
118 + the upgrade on staging or a temporary clone, resolve compatibility issues there, then perform the production
119 + upgrade with a clear plan.
120 + </p>
133 133  
134 - ul {
135 - margin: 0;
136 - padding-left: 18px;
137 - color: @muted;
138 - }
122 + <ol>
123 + <li><strong>Prepare a clone:</strong> copy the relevant database, filesystem and configuration.</li>
124 + <li><strong>Run the upgrade outside production:</strong> record the steps and issues found.</li>
125 + <li><strong>Validate critical features:</strong> login, rights, search, PDFs, workflows, dashboards and integrations.</li>
126 + <li><strong>Plan the production window:</strong> backups, downtime, rollback and communication.</li>
127 + <li><strong>Document the result:</strong> keep notes for the next upgrade cycle.</li>
128 + </ol>
139 139  
140 - li {
141 - margin: 8px 0;
142 - }
130 + <h2 id="common-mistakes">Common mistakes to avoid</h2>
143 143  
144 - a {
145 - color: @brand;
146 - font-weight: 600;
147 - }
148 -}
132 + <ul>
133 + <li><strong>Upgrading directly in production.</strong> Compatibility issues should be discovered before users are affected.</li>
134 + <li><strong>Checking only public pages.</strong> Authentication, restricted spaces and admin features also need validation.</li>
135 + <li><strong>Ignoring custom code.</strong> Custom scripts and extensions often create the real upgrade complexity.</li>
136 + <li><strong>Skipping backup validation.</strong> A backup is useful only if restore expectations are understood.</li>
137 + <li><strong>Keeping no upgrade notes.</strong> Without notes, the next maintenance cycle starts again from uncertainty.</li>
138 + </ul>
149 149  
150 -.resource-cta {
151 - margin-top: 36px;
152 - padding: 22px;
153 - border: 1px solid fade(@brand, 20%);
154 - border-radius: @radius;
155 - background: @brand-bg;
140 + <h2 id="upgrade-rhythm">How often should XWiki be upgraded?</h2>
156 156  
157 - h3 {
158 - margin-top: 0;
159 - }
142 + <p>
143 + For many organizations, a practical rhythm is to stay aligned with the current Long Term Support version
144 + and plan upgrades regularly rather than waiting for a major problem. Some environments can upgrade more
145 + frequently, while heavily customized instances may require more planning.
146 + </p>
160 160  
161 - p {
162 - color: @muted;
163 - }
164 -}
148 + <p>
149 + The important part is not only the exact frequency. It is having an upgrade process that is repeatable:
150 + review, staging validation, production rollout, documentation and follow-up.
151 + </p>
165 165  
166 -@media (max-width: 900px) {
167 - .resource-layout {
168 - grid-template-columns: 1fr;
169 - }
153 + <div class="resource-cta">
154 + <h3>Need help planning an XWiki upgrade?</h3>
155 + <p>
156 + If your XWiki instance is outdated, customized or business-critical, the safest next step is to review
157 + the current version, extensions, infrastructure and validation needs before planning the production upgrade.
158 + </p>
159 + <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request an upgrade review</a>
160 + </div>
170 170  
171 - .resource-sidebar {
172 - position: static;
173 - }
174 -}
162 + </article>
163 + </div>
164 + </div>
165 + </section>
166 +{{/html}}
167 +{{/velocity}}
Agnease.Code.SEODetailsClass[0]
metaDescription
... ... @@ -1,0 +1,1 @@
1 +Learn why regular XWiki upgrades matter for security, stability, extension compatibility and long-term maintenance, especially for production XWiki instances.
metaTitle
... ... @@ -1,0 +1,1 @@
1 +Why Upgrade XWiki Regularly | Security, Stability and LTS Updates