Versioning

Documentation Perspective

• Documentation must be written from the perspective of the latest version.
• Differences between the latest version and the LTS or other supported versions should be documented secondarily using the, using the {{version}} macro, along with the before parameter.
• The documentation content should always reflect the current UI, behavior, and features.

The "Version" Macro

When documentation depends on specific versions of XWiki or on a released extension, you must indicate this using the {{version}} macro.

• For XWiki itself, specify versions more recent or equal to the LTS version, as long as that version is within the currently supported LTS cycle.
• For extensions, specify the released version.

Example result:

This helps readers know if the information applies to their XWiki instance.

Note: When the versions referenced in a {{version}} macro are no longer within the supported LTS cycle, those version markers must be removed.

Documenting a New Feature

When documenting something that did not exist before:

• Use the {{version}} macro, along with the since parameter. Readers need to know if it exists in their version. For example:

  {{version since="16.10.6, 17.3.0RC1"}}
  The Realtime edit actions were included.
  {{/version}}

Documenting UI Changes or Modified Behavior

When describing something that existed before, but works differently now:

• Write the latest behavior normally (no macro).
• Use the before parameter to describe the previous behavior. For example:

  The tab uses the "Language" terminology ({{version before="16.10.12"}}Previously, the tab was using the "Locale" terminology{{/version}}).

  • Note: Some UI changes may not be relevant enough to justify a version macro for showing the old UI. For example:
    • No text was added or modified.
    • The behavior remains the same.
    • The UI element that changed is located in the same area.
      In such cases, adding a version macro with the before parameter would only clutter the page with information that is not really helpful for readers.

Removing Old Documentation

The xwiki.org community only supports the LTS and beyond. Thus, the documentation on xwiki.org should be kept aligned and focus exclusively on supported versions.

Documentation gardening therefore involves:

• Removing documentation and versions macros for versions older than the current LTS cycle.
• Remove mentions of old XWiki versions by removing the versions macros around valid content. This avoids the xwiki.org documentation to be littered with references to old (not supported) versions of XWiki.