Skip to Content
Last modified by Agnease on 2026/05/26 10:58
From version 1.4
edited by Agnease
on 2026/05/12 14:47
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,293 +1,174 @@
1 -{{velocity}}
2 -#set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
3 -{{html clean="false"}}
1 +/* ========== Resource / Article Pages ========== */
4 4  
5 - ## PAGE HEADER
6 - <section class="hero hero-centered service-hero" aria-labelledby="hero-title">
7 - <div class="container hero-inner">
8 - <div class="hero-kicker">
9 - <i class="fa fa-refresh" aria-hidden="true"></i>
10 - XWiki upgrade guidance
11 - </div>
3 +.resource-page {
4 + padding-top: 34px;
5 +}
12 12  
13 - <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%);
14 14  
15 - <p class="lead">
16 - A working XWiki instance can still become outdated, harder to maintain and exposed to avoidable risks
17 - when upgrades are postponed for too long.
18 - </p>
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 + }
19 19  
20 - <p class="hero-support">
21 - Regular upgrades help keep XWiki secure, stable, compatible and easier to evolve, especially when the platform
22 - is used for internal knowledge, documentation, procedures, workflows or business-critical collaboration.
23 - </p>
27 + h1 {
28 + max-width: 820px;
29 + margin: 0 auto 14px;
30 + text-align: center;
31 + line-height: 1.18;
32 + }
24 24  
25 - <div class="hero-actions">
26 - <a class="btn btn-primary" href="$xwiki.getURL('services.xwiki-upgrades')">View upgrade services</a>
27 - <a class="btn btn-secondary" href="#upgrade-tips">Read upgrade tips</a>
28 - </div>
29 - </div>
30 - </section>
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 +}
31 31  
32 - ## WHY IT MATTERS
33 - <section aria-labelledby="why-title">
34 - <div class="container">
35 - <h2 id="why-title">“It still works” is not the same as “it is safe to keep unchanged”</h2>
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 +}
36 36  
37 - <p class="section-intro">
38 - Many XWiki instances continue to run for years with only small visible problems. That can create the impression
39 - that upgrades are optional. In practice, the longer an instance stays behind, the more risk accumulates around
40 - security fixes, extension compatibility, infrastructure changes, custom code and future upgrade effort.
41 - </p>
53 +.resource-content {
54 + color: @text;
55 + font-size: 16px;
56 + line-height: 1.68;
42 42  
43 - <div class="pathways">
44 - <article class="pathway-card">
45 - <div class="pathway-icon">
46 - <i class="fa fa-shield" aria-hidden="true"></i>
47 - </div>
48 - <h3>Security fixes accumulate</h3>
49 - <p>
50 - Older versions may miss security-related fixes and improvements that are already available in newer releases.
51 - </p>
52 - <ul>
53 - <li>Known issues may already be fixed upstream</li>
54 - <li>Public information about vulnerabilities increases risk over time</li>
55 - <li>Security updates are easier to handle when upgrades are regular</li>
56 - </ul>
57 - </article>
58 + h2 {
59 + text-align: left;
60 + margin: 34px 0 12px;
61 + line-height: 1.28;
62 + }
58 58  
59 - <article class="pathway-card">
60 - <div class="pathway-icon">
61 - <i class="fa fa-puzzle-piece" aria-hidden="true"></i>
62 - </div>
63 - <h3>Compatibility becomes harder</h3>
64 - <p>
65 - Extensions, custom applications, authentication integrations and infrastructure components evolve together.
66 - </p>
67 - <ul>
68 - <li>Extensions may require newer XWiki versions</li>
69 - <li>Java, Tomcat and database requirements can change</li>
70 - <li>Large version jumps are harder to validate</li>
71 - </ul>
72 - </article>
64 + h3 {
65 + margin: 24px 0 8px;
66 + line-height: 1.3;
67 + }
73 73  
74 - <article class="pathway-card">
75 - <div class="pathway-icon">
76 - <i class="fa fa-line-chart" aria-hidden="true"></i>
77 - </div>
78 - <h3>Maintenance cost increases</h3>
79 - <p>
80 - The longer upgrades are postponed, the more difficult it becomes to understand what changed and what may break.
81 - </p>
82 - <ul>
83 - <li>More release notes to review</li>
84 - <li>More compatibility checks to perform</li>
85 - <li>More risk around custom code and old assumptions</li>
86 - </ul>
87 - </article>
88 - </div>
89 - </div>
90 - </section>
69 + p {
70 + margin: 0 0 16px;
71 + }
91 91  
92 - ## WHAT TO REVIEW
93 - <section id="upgrade-tips" class="services" aria-labelledby="tips-title">
94 - <div class="container">
95 - <h2 id="tips-title">Practical tips before planning an XWiki upgrade</h2>
73 + ul,
74 + ol {
75 + margin: 0 0 18px;
76 + padding-left: 22px;
77 + }
96 96  
97 - <p class="section-intro">
98 - A good upgrade starts before the installation step. The most useful preparation is to understand the current
99 - platform, identify what is business-critical and validate the upgrade outside production.
100 - </p>
79 + li {
80 + margin: 6px 0;
81 + }
101 101  
102 - <div class="services-grid">
103 - <article class="service">
104 - <div class="service-icon" aria-hidden="true">
105 - <i class="fa fa-code-fork"></i>
106 - </div>
107 - <div class="service-body">
108 - <h4>Check your current version and target version</h4>
109 - <p>
110 - Identify the current XWiki version, the desired target version and whether intermediate upgrade steps are needed.
111 - </p>
112 - </div>
113 - </article>
83 + strong {
84 + color: @text;
85 + }
86 +}
114 114  
115 - <article class="service">
116 - <div class="service-icon" aria-hidden="true">
117 - <i class="fa fa-puzzle-piece"></i>
118 - </div>
119 - <div class="service-body">
120 - <h4>Review installed extensions</h4>
121 - <p>
122 - List installed extensions and check whether they are compatible with the target XWiki version.
123 - </p>
124 - </div>
125 - </article>
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;
126 126  
127 - <article class="service">
128 - <div class="service-icon" aria-hidden="true">
129 - <i class="fa fa-code"></i>
130 - </div>
131 - <div class="service-body">
132 - <h4>Identify custom code</h4>
133 - <p>
134 - Review custom macros, Velocity scripts, Java components, UI extensions, sheets, templates and local changes.
135 - </p>
136 - </div>
137 - </article>
95 + p:last-child {
96 + margin-bottom: 0;
97 + }
98 +}
138 138  
139 - <article class="service">
140 - <div class="service-icon" aria-hidden="true">
141 - <i class="fa fa-lock"></i>
142 - </div>
143 - <div class="service-body">
144 - <h4>Validate authentication</h4>
145 - <p>
146 - LDAP, Active Directory, SSO, OIDC, SAML and MFA configurations should be tested carefully after the upgrade.
147 - </p>
148 - </div>
149 - </article>
100 +.resource-checklist {
101 + margin: 18px 0 24px;
102 + padding: 0;
103 + list-style: none;
150 150  
151 - <article class="service">
152 - <div class="service-icon" aria-hidden="true">
153 - <i class="fa fa-database"></i>
154 - </div>
155 - <div class="service-body">
156 - <h4>Prepare backups and a staging clone</h4>
157 - <p>
158 - Never treat production as the first test. Validate the upgrade on staging or a temporary clone first.
159 - </p>
160 - </div>
161 - </article>
105 + li {
106 + position: relative;
107 + padding: 10px 0 10px 34px;
108 + border-bottom: 1px solid @line;
162 162  
163 - <article class="service">
164 - <div class="service-icon" aria-hidden="true">
165 - <i class="fa fa-check-square-o"></i>
166 - </div>
167 - <div class="service-body">
168 - <h4>Create a validation checklist</h4>
169 - <p>
170 - Test login, permissions, search, dashboards, PDFs, custom applications, jobs, important pages and integrations.
171 - </p>
172 - </div>
173 - </article>
174 - </div>
175 - </div>
176 - </section>
110 + &:before {
111 + content: "\f00c";
112 + font-family: FontAwesome;
113 + position: absolute;
114 + left: 0;
115 + top: 11px;
116 + color: @brand;
117 + }
118 + }
119 +}
177 177  
178 - ## SAFE PROCESS
179 - <section class="split-section" aria-labelledby="process-title">
180 - <div class="container">
181 - <div class="split-grid">
182 - <div class="split-copy">
183 - <h2 id="process-title">The safest upgrade is the one rehearsed before production</h2>
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;
184 184  
185 - <p>
186 - A production upgrade should not be the first time the process is tested. A staging environment or temporary
187 - clone allows problems to be discovered before they affect users.
188 - </p>
130 + h4 {
131 + margin: 0 0 10px;
132 + }
189 189  
190 - <p>
191 - This is especially important when the instance includes custom applications, authentication integrations,
192 - PDF exports, workflows, advanced permissions or business-critical documentation.
193 - </p>
194 - </div>
134 + ul {
135 + margin: 0;
136 + padding-left: 18px;
137 + color: @muted;
138 + }
195 195  
196 - <ol class="process-list">
197 - <li>
198 - <strong>Prepare a staging clone</strong>
199 - Copy the relevant database, filesystem and configuration into a controlled non-production environment.
200 - </li>
201 - <li>
202 - <strong>Run the upgrade there first</strong>
203 - Apply the upgrade, resolve compatibility issues and record the steps required.
204 - </li>
205 - <li>
206 - <strong>Validate business-critical features</strong>
207 - Confirm that authentication, rights, search, exports, custom apps and important workflows still work.
208 - </li>
209 - <li>
210 - <strong>Plan the production window</strong>
211 - Define backup, downtime, rollback and communication expectations before touching production.
212 - </li>
213 - <li>
214 - <strong>Document the result</strong>
215 - Keep upgrade notes, observed issues and follow-up recommendations for the next maintenance cycle.
216 - </li>
217 - </ol>
218 - </div>
219 - </div>
220 - </section>
140 + li {
141 + margin: 8px 0;
142 + }
221 221  
222 - ## COMMON MISTAKES
223 - <section aria-labelledby="mistakes-title">
224 - <div class="container">
225 - <h2 id="mistakes-title">Common mistakes to avoid</h2>
144 + a {
145 + color: @brand;
146 + font-weight: 600;
147 + }
148 +}
226 226  
227 - <p class="section-intro">
228 - Most difficult upgrades are not difficult because XWiki cannot be upgraded. They become difficult because
229 - the environment, customizations or validation steps were not understood early enough.
230 - </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;
231 231  
232 - <div class="widgets">
233 - <article class="widget">
234 - <div class="icon" aria-hidden="true">
235 - <i class="fa fa-warning"></i>
236 - <h4>Upgrading<br />directly in production</h4>
237 - </div>
238 - <p>
239 - Production should not be the first place where compatibility issues are discovered.
240 - </p>
241 - </article>
157 + h3 {
158 + margin-top: 0;
159 + }
242 242  
243 - <article class="widget">
244 - <div class="icon" aria-hidden="true">
245 - <i class="fa fa-puzzle-piece"></i>
246 - <h4>Ignoring<br />extensions</h4>
247 - </div>
248 - <p>
249 - Extensions and custom code often create the real upgrade complexity.
250 - </p>
251 - </article>
161 + p {
162 + color: @muted;
163 + }
164 +}
252 252  
253 - <article class="widget">
254 - <div class="icon" aria-hidden="true">
255 - <i class="fa fa-lock"></i>
256 - <h4>Testing only<br />public pages</h4>
257 - </div>
258 - <p>
259 - Login, permissions, restricted spaces and admin features should also be validated.
260 - </p>
261 - </article>
166 +@media (max-width: 900px) {
167 + .resource-layout {
168 + grid-template-columns: 1fr;
169 + }
262 262  
263 - <article class="widget">
264 - <div class="icon" aria-hidden="true">
265 - <i class="fa fa-file-text-o"></i>
266 - <h4>No upgrade<br />notes</h4>
267 - </div>
268 - <p>
269 - Without notes, every future upgrade starts again from uncertainty.
270 - </p>
271 - </article>
272 - </div>
273 - </div>
274 - </section>
275 -
276 - ## CTA
277 - <section class="cta-section" aria-labelledby="cta-title">
278 - <div class="container">
279 - <div class="cta-panel">
280 - <h2 id="cta-title">Need help planning an XWiki upgrade?</h2>
281 -
282 - <p>
283 - If your XWiki instance is outdated, customized or business-critical, the safest next step is to review
284 - the current version, extensions, infrastructure and validation needs before planning the production upgrade.
285 - </p>
286 -
287 - <a class="btn btn-primary" href="$xwiki.getURL('services.xwiki-upgrades')">View XWiki upgrade services</a>
288 - </div>
289 - </div>
290 - </section>
291 -
292 -{{/html}}
293 -{{/velocity}}
171 + .resource-sidebar {
172 + position: static;
173 + }
174 +}