Changes for page How to Customize XWiki Without Creating Upgrade Problems

Last modified by Agnease on 2026/05/26 11:00

Manage
- Copy
Actions
- Export
- Print Preview
Viewers
- Source
- Siblings
- Content
- Comments
- Attachments
- History
- Information
- Likes

From 12.2 to 12.1

From version 12.5

edited by Agnease
on 2026/05/26 11:00

Change comment: There is no comment for this version

To version 12.2

edited by Agnease
on 2026/05/26 10:49

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -110,15 +110,6 @@
              for related checks around permissions, authentication, extensions, infrastructure and operational practices.
            </p>
--          <div class="resource-inline-cta">
--            <p>
--              <strong>Unsure how maintainable your XWiki customizations are?</strong>
--              A customization review can help identify hidden scripts, undocumented logic,
--              upgrade risks and features that should be documented, cleaned up or packaged properly.
--            </p>
--            <a class="btn btn-secondary" href="$xwiki.getURL('contact.WebHome')">Request a customization review</a>
--          </div>
--
            <h2 id="safe-model">A safer model for XWiki custom work</h2>
            <h3>1. Keep custom code separate from standard XWiki pages</h3>
@@ -225,50 +225,40 @@
            <h2 id="custom-development-faq">XWiki custom development FAQ</h2>
--          <details class="resource-faq-item" open>
--            <summary>Does custom development make XWiki harder to upgrade?</summary>
--            <p>
--              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.
--            </p>
--          </details>
++          <h3>Does custom development make XWiki harder to upgrade?</h3>
++          <p>
++            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.
++          </p>
--          <details class="resource-faq-item">
--            <summary>Where should XWiki custom code be stored?</summary>
--            <p>
--              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.
--            </p>
--          </details>
++          <h3>Where should XWiki custom code be stored?</h3>
++          <p>
++            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.
++          </p>
--          <details class="resource-faq-item">
--            <summary>When should an XWiki customization become an extension?</summary>
--            <p>
--              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.
--            </p>
--          </details>
++          <h3>When should an XWiki customization become an extension?</h3>
++          <p>
++            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.
++          </p>
--          <details class="resource-faq-item">
--            <summary>What should be tested after an XWiki upgrade?</summary>
--            <p>
--              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.
--            </p>
--          </details>
++          <h3>What should be tested after an XWiki upgrade?</h3>
++          <p>
++            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.
++          </p>
--          <details class="resource-faq-item">
--            <summary>Why should configuration be kept outside custom code?</summary>
--            <p>
--              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.
--            </p>
--          </details>
++          <h3>Why should configuration be kept outside custom code?</h3>
++          <p>
++            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.
++          </p>
            <div class="resource-note">
              <p>