Skip to Content
Last modified by Agnease on 2026/05/26 11:00
From version 12.5
edited by Agnease
on 2026/05/26 11:00
Change comment: There is no comment for this version
To version 8.1
edited by Agnease
on 2026/05/22 06:12
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -How to Customize XWiki Without Creating Upgrade Problems
1 +xwiki-custom-development
Content
... ... @@ -32,7 +32,6 @@
32 32   <li><a href="#upgrade-validation">Upgrade validation</a></li>
33 33   <li><a href="#practical-checklist">Checklist</a></li>
34 34   <li><a href="#strategic-advantage">Strategic advantage</a></li>
35 - <li><a href="#custom-development-faq">FAQ</a></li>
36 36   </ul>
37 37   </aside>
38 38  
... ... @@ -53,20 +53,6 @@
53 53  
54 54   <div class="resource-note">
55 55   <p>
56 - <strong>In practice:</strong> XWiki custom development should be separated from standard platform pages,
57 - documented, kept under source control, tested on staging and reviewed during upgrades. This makes custom
58 - features easier to maintain instead of turning them into hidden dependencies.
59 - </p>
60 - </div>
61 -
62 - <p>
63 - XWiki custom development is the process of adapting the platform with custom pages, classes, objects, sheets,
64 - templates, scripts, macros, UI extensions, Java components or integrations. The goal is to support real
65 - business processes while keeping the instance understandable, maintainable and upgrade-aware.
66 - </p>
67 -
68 - <div class="resource-note">
69 - <p>
70 70   <strong>The main point:</strong> custom code is not the problem. Uncontrolled custom code is. XWiki can be
71 71   customized safely when changes are separated from standard pages, tracked, documented and tested.
72 72   </p>
... ... @@ -104,21 +104,6 @@
104 104   path.
105 105   </p>
106 106  
107 - <p>
108 - Customizations should also be reviewed as part of the wider platform risk model. See
109 - <a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>
110 - for related checks around permissions, authentication, extensions, infrastructure and operational practices.
111 - </p>
112 -
113 - <div class="resource-inline-cta">
114 - <p>
115 - <strong>Unsure how maintainable your XWiki customizations are?</strong>
116 - A customization review can help identify hidden scripts, undocumented logic,
117 - upgrade risks and features that should be documented, cleaned up or packaged properly.
118 - </p>
119 - <a class="btn btn-secondary" href="$xwiki.getURL('contact.WebHome')">Request a customization review</a>
120 - </div>
121 -
122 122   <h2 id="safe-model">A safer model for XWiki custom work</h2>
123 123  
124 124   <h3>1. Keep custom code separate from standard XWiki pages</h3>
... ... @@ -136,11 +136,11 @@
136 136   into a maintainable part of the platform.
137 137   </p>
138 138  
139 - <h3>3. Keep custom code under source control</h3>
109 + <h3>3. Track important changes in a version control system</h3>
140 140   <p>
141 - Custom development should not exist only inside the production wiki. Java code, scripts, XAR packages,
142 - deployment files and templates should be stored in a source control system, such as Git. This gives the team a
143 - history of what changed, when it changed and why.
111 + Serious custom development should not exist only inside the production wiki. Java code, scripts, XAR packages,
112 + deployment files and important templates should be stored in a version control system, such as Git. This gives
113 + the team a history of what changed, when it changed and why.
144 144   </p>
145 145  
146 146   <h3>4. Choose the right implementation level</h3>
... ... @@ -172,11 +172,6 @@
172 172   touched.
173 173   </p>
174 174  
175 - <p>
176 - For a broader upgrade preparation model, see
177 - <a href="$xwiki.getURL('resources.why-upgrade-xwiki')">why regular XWiki upgrades matter</a>.
178 - </p>
179 -
180 180   <div class="resource-note">
181 181   <p>
182 182   <strong>A practical rule:</strong> production can receive urgent fixes when necessary, but it should not become
... ... @@ -185,26 +185,12 @@
185 185   </p>
186 186   </div>
187 187  
188 - <div class="resource-inline-cta">
189 - <p>
190 - <strong>Not sure how risky your current XWiki version is?</strong>
191 - A short technical review can clarify the upgrade path, extension compatibility,
192 - custom code risks and validation needs before production is touched.
193 - </p>
194 - <a class="btn btn-secondary" href="$xwiki.getURL('contact.WebHome')">Request a quick review</a>
195 - </div>
153 + <h2 id="practical-checklist">A compact checklist</h2>
196 196  
197 - <h2 id="practical-checklist">XWiki custom development checklist</h2>
198 -
199 - <p>
200 - A maintainable XWiki customization should be easy to locate, explain, test and update. The following checklist
201 - can be used as a starting point when reviewing existing custom work or planning a new feature.
202 - </p>
203 -
204 204   <ul class="resource-checklist">
205 205   <li>Separate custom pages, scripts and configuration from standard XWiki content.</li>
206 206   <li>Document the business purpose, technical location and validation steps.</li>
207 - <li>Keep custom code and important assets under source control, for example in Git.</li>
158 + <li>Use a version control system, such as Git, for code and important assets.</li>
208 208   <li>Test custom features on staging before production upgrades.</li>
209 209   <li>Review old customizations and remove what is no longer used.</li>
210 210   </ul>
... ... @@ -223,62 +223,6 @@
223 223   flexible without becoming fragile.
224 224   </p>
225 225  
226 - <h2 id="custom-development-faq">XWiki custom development FAQ</h2>
227 -
228 - <details class="resource-faq-item" open>
229 - <summary>Does custom development make XWiki harder to upgrade?</summary>
230 - <p>
231 - Not automatically. Custom development becomes harder to upgrade when it is undocumented, mixed with regular
232 - content, applied directly in production or missing from the upgrade validation plan. Well-organized custom work
233 - can remain maintainable across upgrades.
234 - </p>
235 - </details>
236 -
237 - <details class="resource-faq-item">
238 - <summary>Where should XWiki custom code be stored?</summary>
239 - <p>
240 - Custom wiki pages, scripts, templates and configuration should usually be kept in dedicated technical spaces.
241 - Code and important assets should also be tracked in a source control system, such as Git, so changes are not
242 - stored only in the production wiki.
243 - </p>
244 - </details>
245 -
246 - <details class="resource-faq-item">
247 - <summary>When should an XWiki customization become an extension?</summary>
248 - <p>
249 - Packaging a customization as an extension is useful when the feature becomes complex, reusable, business-critical
250 - or shared across multiple instances. Java components, event listeners, scheduled jobs and integrations often
251 - benefit from an extension-based approach.
252 - </p>
253 - </details>
254 -
255 - <details class="resource-faq-item">
256 - <summary>What should be tested after an XWiki upgrade?</summary>
257 - <p>
258 - Besides standard pages, the validation should include custom dashboards, templates, macros, workflows,
259 - permissions, notifications, PDF exports, scheduled jobs, integrations and any custom applications used by the
260 - organization.
261 - </p>
262 - </details>
263 -
264 - <details class="resource-faq-item">
265 - <summary>Why should configuration be kept outside custom code?</summary>
266 - <p>
267 - Values such as group names, target spaces, external URLs, email recipients and workflow settings can change over
268 - time. Keeping them in configuration pages or preference objects makes custom features easier to adapt without
269 - changing the implementation.
270 - </p>
271 - </details>
272 -
273 - <div class="resource-note">
274 - <p>
275 - Related resources:
276 - <a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>
277 - and
278 - <a href="$xwiki.getURL('resources.why-upgrade-xwiki')">why regular XWiki upgrades matter</a>
279 - </p>
280 - </div>
281 -
282 282   <div class="resource-cta">
283 283   <h3>Need help reviewing XWiki customizations?</h3>
284 284   <p>
... ... @@ -294,54 +294,5 @@
294 294   </div>
295 295   </section>
296 296  
297 - <script type="application/ld+json">
298 - {
299 - "@context": "https://schema.org",
300 - "@type": "FAQPage",
301 - "mainEntity": [
302 - {
303 - "@type": "Question",
304 - "name": "Does custom development make XWiki harder to upgrade?",
305 - "acceptedAnswer": {
306 - "@type": "Answer",
307 - "text": "Not automatically. Custom development becomes harder to upgrade when it is undocumented, mixed with regular content, applied directly in production or missing from the upgrade validation plan. Well-organized custom work can remain maintainable across upgrades."
308 - }
309 - },
310 - {
311 - "@type": "Question",
312 - "name": "Where should XWiki custom code be stored?",
313 - "acceptedAnswer": {
314 - "@type": "Answer",
315 - "text": "Custom wiki pages, scripts, templates and configuration should usually be kept in dedicated technical spaces. Code and important assets should also be tracked in a source control system, such as Git, so changes are not stored only in the production wiki."
316 - }
317 - },
318 - {
319 - "@type": "Question",
320 - "name": "When should an XWiki customization become an extension?",
321 - "acceptedAnswer": {
322 - "@type": "Answer",
323 - "text": "Packaging a customization as an extension is useful when the feature becomes complex, reusable, business-critical or shared across multiple instances. Java components, event listeners, scheduled jobs and integrations often benefit from an extension-based approach."
324 - }
325 - },
326 - {
327 - "@type": "Question",
328 - "name": "What should be tested after an XWiki upgrade?",
329 - "acceptedAnswer": {
330 - "@type": "Answer",
331 - "text": "Besides standard pages, the validation should include custom dashboards, templates, macros, workflows, permissions, notifications, PDF exports, scheduled jobs, integrations and any custom applications used by the organization."
332 - }
333 - },
334 - {
335 - "@type": "Question",
336 - "name": "Why should configuration be kept outside custom code?",
337 - "acceptedAnswer": {
338 - "@type": "Answer",
339 - "text": "Values such as group names, target spaces, external URLs, email recipients and workflow settings can change over time. Keeping them in configuration pages or preference objects makes custom features easier to adapt without changing the implementation."
340 - }
341 - }
342 - ]
343 - }
344 - </script>
345 -
346 346  {{/html}}
347 347  {{/velocity}}
Agnease.Code.SEODetailsClass[0]
metaTitle
... ... @@ -1,1 +1,1 @@
1 -How to Customize XWiki Without Creating Upgrade Problems | Agnease
1 +XWiki Custom Development Without Upgrade Problems | Agnease