Wiki source code of Versioning
Last modified by Eleni Cojocariu on 2026/02/04 15:25
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | == Documentation Perspective == | ||
| 6 | |||
| 7 | * Documentation must be written from the perspective of the latest version. | ||
| 8 | * Differences between the latest version and the LTS or other supported versions should be documented secondarily using the, using the [[##~~{~~{version}}## macro>>doc:xwiki:documentation.extensions.user.documentation.version-macro.WebHome]], along with the ##before## parameter. | ||
| 9 | * The documentation content should always reflect the current UI, behavior, and features. | ||
| 10 | |||
| 11 | == The "Version" Macro == | ||
| 12 | |||
| 13 | When documentation depends on specific versions of XWiki or on a released extension, you must indicate this using the [[##~~{~~{version}}## macro>>xwiki:DocApp.Code.VersionMacro]]. | ||
| 14 | |||
| 15 | * For XWiki itself, specify [[versions more recent or equal to the LTS version>>xwiki:Main.Support||anchor="HCommunitySupport"]], as long as that version is within the currently supported [[LTS cycle>>xwiki:Main.Support||anchor="HCommunitySupport"]]. | ||
| 16 | * For extensions, specify the released version. | ||
| 17 | |||
| 18 | Example result: | ||
| 19 | |||
| 20 | {{gallery}} | ||
| 21 | image:version-macro-before.png | ||
| 22 | image:version-macro-since.png | ||
| 23 | {{/gallery}} | ||
| 24 | |||
| 25 | This helps readers know if the information applies to their XWiki instance. | ||
| 26 | |||
| 27 | Note: When the versions referenced in a ##~{~{version}}## macro are no longer within the supported LTS cycle, those version markers must be [[removed>>||anchor="HRemovingOldDocumentation"]]. | ||
| 28 | |||
| 29 | == Documenting a New Feature == | ||
| 30 | |||
| 31 | When documenting something that did not exist before: | ||
| 32 | |||
| 33 | * Use the ##~{~{version}}## macro, along with the ##since## parameter. Readers need to know if it exists in their version. For example:((( | ||
| 34 | {{code language="none"}} | ||
| 35 | {{version since="16.10.6, 17.3.0RC1"}} | ||
| 36 | The Realtime edit actions were included. | ||
| 37 | {{/version}} | ||
| 38 | {{/code}} | ||
| 39 | ))) | ||
| 40 | |||
| 41 | == Documenting UI Changes or Modified Behavior == | ||
| 42 | |||
| 43 | When describing something that existed before, but works differently now: | ||
| 44 | |||
| 45 | * Write the latest behavior normally (no macro). | ||
| 46 | * Use the ##before## parameter to describe the previous behavior. For example:((( | ||
| 47 | {{code language="none"}} | ||
| 48 | The tab uses the "Language" terminology ({{version before="16.10.12"}}Previously, the tab was using the "Locale" terminology{{/version}}). | ||
| 49 | {{/code}} | ||
| 50 | ))) | ||
| 51 | ** Note: Some UI changes may not be relevant enough to justify a version macro for showing the old UI. For example: | ||
| 52 | *** No text was added or modified. | ||
| 53 | *** The behavior remains the same. | ||
| 54 | *** The UI element that changed is located in the same area. | ||
| 55 | 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. | ||
| 56 | |||
| 57 | == Removing Old Documentation == | ||
| 58 | |||
| 59 | The xwiki.org community only [[supports the LTS and beyond>>xwiki:Main.Support||anchor="HCommunitySupport"]]. Thus, the documentation on xwiki.org should be kept aligned and focus exclusively on supported versions. | ||
| 60 | |||
| 61 | Documentation gardening therefore involves: | ||
| 62 | |||
| 63 | * Removing documentation and [[versions macros>>||anchor="HAffectedVersions"]] for versions older than the current [[LTS cycle>>dev:Community.VersioningAndReleasePractices.WebHome||anchor="HReleaseCyclesandReleaseStrategy"]]. | ||
| 64 | * Remove mentions of old XWiki versions by removing the [[versions macros>>||anchor="HAffectedVersions"]] around valid content. This avoids the xwiki.org documentation to be littered with references to old (not supported) versions of XWiki. |
