Changes for page How to Customize XWiki Without Creating Upgrade Problems

Last modified by Alex Cotiuga on 2026/07/03 15:51

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

From 12.1 to 12.2

From version 12.2

edited by Alex Cotiuga
on 2026/05/26 10:49

Change comment: There is no comment for this version

To version 13.2

edited by Alex Cotiuga
on 2026/07/03 15:51

Change comment: There is no comment for this version

Raw
Rendered

Summary

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

Details

Page properties

Default language

...	...	@@ -1,1 +1,0 @@
1		-en

Hidden

@@ -1,1 +1,1 @@
--false
++true

Content

@@ -110,6 +110,15 @@
              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>
@@ -216,40 +216,50 @@
            <h2 id="custom-development-faq">XWiki custom development FAQ</h2>
--          <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" 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>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>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>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>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>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>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>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>
++          <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>
            <div class="resource-note">
              <p>
@@ -259,22 +259,25 @@
                <a href="$xwiki.getURL('resources.why-upgrade-xwiki')">why regular XWiki upgrades matter</a>
              </p>
            </div>
--
--          <div class="resource-cta">
--            <h3>Need help reviewing XWiki customizations?</h3>
--            <p>
--              If your XWiki instance includes custom scripts, dashboards, workflows, templates, integrations or Java
--              extensions, a customization review can help identify what is safe, what needs documentation and what should be
--              tested before the next upgrade.
--            </p>
--            <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request a customization review</a>
--          </div>
--
          </article>
        </div>
      </div>
    </section>
++  <section class="cta-section" aria-labelledby="xwiki-custom-development-cta-title">
++    <div class="container">
++      <div class="cta-panel">
++        <h2 id="xwiki-custom-development-cta-title">Need help reviewing XWiki customizations?</h2>
++        <p>
++          If your XWiki instance includes custom scripts, dashboards, workflows, templates, integrations or Java
++          extensions, a customization review can help identify what is safe, what needs documentation and what should be
++          tested before the next upgrade.
++        </p>
++        <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request a customization review</a>
++      </div>
++    </div>
++  </section>
++
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",