Release Note Structure
Explanation
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 or render it from a displayer of your own.
Page hierarchy
Every page of the application sits below one top-level space, ReleaseNotes by default:
ReleaseNotes.WebHome the application home page
ReleaseNotes.Data.WebHome the data root
ReleaseNotes.Data.<Product>.<ShortVersion>.WebHome the release note
ReleaseNotes.Data.<Product>.<ShortVersion>.Entry001.WebHome a change
ReleaseNotes.Data.<Product>.<ShortVersion>.Contributors.WebHome the creditsThe short version is the page name and is parsed as the version, so the naming carries meaning rather than being cosmetic.
Two xobjects per entry
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.
Never hardcode the top-level space
Each page resolves the space it was installed in at runtime rather than naming it:
#set ($topSpace = $doc.documentReference.extractFirstReference('SPACE').getName())
#set ($object = $doc.getObject("${topSpace}.Code.EntryClass"))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.
Version aggregation
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.
FAQ
Why does an entry need two xobjects rather than one?
The envelope is shared by every kind of entry, so a query can find and locate entries without knowing which payload they carry.
How do I exclude a change that was superseded before the final release?
Pass its page reference to the exclusions parameter of the releasenotechanges macro on the final release note.
