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 1.4
edited by Agnease
on 2026/05/12 14:47
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,174 +1,293 @@
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 + ## 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>
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%);
13 + <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 - }
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>
26 26  
27 - h1 {
28 - max-width: 820px;
29 - margin: 0 auto 14px;
30 - text-align: center;
31 - line-height: 1.18;
32 - }
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>
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 -}
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>
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 -}
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>
52 52  
53 -.resource-content {
54 - color: @text;
55 - font-size: 16px;
56 - line-height: 1.68;
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>
57 57  
58 - h2 {
59 - text-align: left;
60 - margin: 34px 0 12px;
61 - line-height: 1.28;
62 - }
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>
63 63  
64 - h3 {
65 - margin: 24px 0 8px;
66 - line-height: 1.3;
67 - }
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>
68 68  
69 - p {
70 - margin: 0 0 16px;
71 - }
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>
72 72  
73 - ul,
74 - ol {
75 - margin: 0 0 18px;
76 - padding-left: 22px;
77 - }
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>
78 78  
79 - li {
80 - margin: 6px 0;
81 - }
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>
82 82  
83 - strong {
84 - color: @text;
85 - }
86 -}
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>
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;
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>
94 94  
95 - p:last-child {
96 - margin-bottom: 0;
97 - }
98 -}
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>
99 99  
100 -.resource-checklist {
101 - margin: 18px 0 24px;
102 - padding: 0;
103 - list-style: none;
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>
104 104  
105 - li {
106 - position: relative;
107 - padding: 10px 0 10px 34px;
108 - border-bottom: 1px solid @line;
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>
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 -}
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>
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;
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>
129 129  
130 - h4 {
131 - margin: 0 0 10px;
132 - }
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>
133 133  
134 - ul {
135 - margin: 0;
136 - padding-left: 18px;
137 - color: @muted;
138 - }
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>
139 139  
140 - li {
141 - margin: 8px 0;
142 - }
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>
143 143  
144 - a {
145 - color: @brand;
146 - font-weight: 600;
147 - }
148 -}
222 + ## COMMON MISTAKES
223 + <section aria-labelledby="mistakes-title">
224 + <div class="container">
225 + <h2 id="mistakes-title">Common mistakes to avoid</h2>
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;
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>
156 156  
157 - h3 {
158 - margin-top: 0;
159 - }
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>
160 160  
161 - p {
162 - color: @muted;
163 - }
164 -}
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>
165 165  
166 -@media (max-width: 900px) {
167 - .resource-layout {
168 - grid-template-columns: 1fr;
169 - }
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>
170 170  
171 - .resource-sidebar {
172 - position: static;
173 - }
174 -}
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}}