Wiki source code of Release Note Structure
Last modified by Vincent Massol on 2026/08/28 22:09
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | A release note is a small tree of ordinary wiki pages carrying xobjects. Understanding that tree is what lets you query it from the [[getChanges macro>>doc:documentation.extensions.dev.release-notes.getchanges-macro.WebHome]] or render it from a displayer of your own. | ||
| 2 | |||
| 3 | {{plantuml}} | ||
| 4 | @startuml | ||
| 5 | !theme bluegray | ||
| 6 | skinparam shadowing false | ||
| 7 | |||
| 8 | object "**<ShortVersion>.WebHome**\nthe release note" as rn { | ||
| 9 | ReleaseNoteClass | ||
| 10 | product, version, date, released | ||
| 11 | } | ||
| 12 | |||
| 13 | object "**Entry001.WebHome**\na change" as entry { | ||
| 14 | EntryClass (type = Change) | ||
| 15 | Change.ChangeClass | ||
| 16 | title, summary, description | ||
| 17 | audience, importance, category, screenshots | ||
| 18 | } | ||
| 19 | |||
| 20 | object "**Contributors.WebHome**\nthe credits" as contrib { | ||
| 21 | EntryClass (type = Contributors) | ||
| 22 | ContributorsClass | ||
| 23 | contributors | ||
| 24 | } | ||
| 25 | |||
| 26 | rn *-- entry | ||
| 27 | rn *-- contrib | ||
| 28 | @enduml | ||
| 29 | {{/plantuml}} | ||
| 30 | |||
| 31 | == Page hierarchy == | ||
| 32 | |||
| 33 | Every page of the application sits below one top-level space, ##ReleaseNotes## by default: | ||
| 34 | |||
| 35 | {{code language="none"}} | ||
| 36 | ReleaseNotes.WebHome the application home page | ||
| 37 | ReleaseNotes.Data.WebHome the data root | ||
| 38 | ReleaseNotes.Data.<Product>.<ShortVersion>.WebHome the release note | ||
| 39 | ReleaseNotes.Data.<Product>.<ShortVersion>.Entry001.WebHome a change | ||
| 40 | ReleaseNotes.Data.<Product>.<ShortVersion>.Contributors.WebHome the credits | ||
| 41 | {{/code}} | ||
| 42 | |||
| 43 | The short version is the page name and is parsed as the version, so the naming carries meaning rather than being cosmetic. | ||
| 44 | |||
| 45 | == Two xobjects per entry == | ||
| 46 | |||
| 47 | An entry page always carries two xobjects. ##EntryClass## is the envelope: it says which ##product## and ##version## the entry belongs to and whether its ##type## is ##Change## or ##Contributors##, and it is what every query matches on. The second object carries the payload, either ##Change.ChangeClass## or ##ContributorsClass##. An entry that is missing its ##EntryClass## object is invisible to the whole application even though the page renders. | ||
| 48 | |||
| 49 | == Never hardcode the top-level space == | ||
| 50 | |||
| 51 | Each page resolves the space it was installed in at runtime rather than naming it: | ||
| 52 | |||
| 53 | {{code language="velocity"}} | ||
| 54 | #set ($topSpace = $doc.documentReference.extractFirstReference('SPACE').getName()) | ||
| 55 | #set ($object = $doc.getObject("${topSpace}.Code.EntryClass")) | ||
| 56 | {{/code}} | ||
| 57 | |||
| 58 | That is what lets an administrator copy or rename the whole application to another top-level space, so any page you add must follow the same pattern. | ||
| 59 | |||
| 60 | == Version aggregation == | ||
| 61 | |||
| 62 | A release note derives the versions it queries from its own page name. ##8.3M1## queries ##8.3-milestone-1## and ##8.3RC1## queries ##8.3-rc-1##, while a plain ##8.3## queries ##8.3## together with every milestone and release candidate of that version. This is why a final release note lists the changes of its milestones without them being copied. |
