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

Summary

Details

Page properties
Content
... ... @@ -1,174 +1,168 @@
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="resource-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 + <article class="resource-content">
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 -}
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>
52 52  
53 -.resource-content {
54 - color: @text;
55 - font-size: 16px;
56 - line-height: 1.68;
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>
57 57  
58 - h2 {
59 - text-align: left;
60 - margin: 34px 0 12px;
61 - line-height: 1.28;
62 - }
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>
63 63  
64 - h3 {
65 - margin: 24px 0 8px;
66 - line-height: 1.3;
67 - }
48 + <h2 id="why-it-matters">Why regular XWiki upgrades matter</h2>
68 68  
69 - p {
70 - margin: 0 0 16px;
71 - }
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>
72 72  
73 - ul,
74 - ol {
75 - margin: 0 0 18px;
76 - padding-left: 22px;
77 - }
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>
78 78  
79 - li {
80 - margin: 6px 0;
81 - }
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>
82 82  
83 - strong {
84 - color: @text;
85 - }
86 -}
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>
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;
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>
94 94  
95 - p:last-child {
96 - margin-bottom: 0;
97 - }
98 -}
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>
99 99  
100 -.resource-checklist {
101 - margin: 18px 0 24px;
102 - padding: 0;
103 - list-style: none;
89 + <h2 id="upgrade-checklist">Practical checklist before planning an upgrade</h2>
104 104  
105 - li {
106 - position: relative;
107 - padding: 10px 0 10px 34px;
108 - border-bottom: 1px solid @line;
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>
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 -}
103 + <h2 id="safe-process">A safer upgrade process</h2>
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;
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>
129 129  
130 - h4 {
131 - margin: 0 0 10px;
132 - }
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>
133 133  
134 - ul {
135 - margin: 0;
136 - padding-left: 18px;
137 - color: @muted;
138 - }
119 + <h2 id="common-mistakes">Common mistakes to avoid</h2>
139 139  
140 - li {
141 - margin: 8px 0;
142 - }
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>
143 143  
144 - a {
145 - color: @brand;
146 - font-weight: 600;
147 - }
148 -}
129 + <h2 id="upgrade-rhythm">How often should XWiki be upgraded?</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;
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>
156 156  
157 - h3 {
158 - margin-top: 0;
159 - }
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>
160 160  
161 - p {
162 - color: @muted;
163 - }
164 -}
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>
165 165  
166 -@media (max-width: 900px) {
167 - .resource-layout {
168 - grid-template-columns: 1fr;
169 - }
151 + </article>
170 170  
171 - .resource-sidebar {
172 - position: static;
173 - }
174 -}
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 +{{/html}}
168 +{{/velocity}}