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

Summary

Details

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