Group changes by Category

Attempting to implement this surfaced enough open questions that I think we need a better spec first. Here is what the current implementation (ReleaseNotes.Code.Change.GetChangesMacro) makes ambiguous or hard.

1. What "grouped" means relative to the existing importance order

getChanges sorts with order by changes.importance desc, doc.fullName. No displayer renders the importance, so its only visible effect is that order: important changes come first. Three candidate semantics:

• order by changes.category, changes.importance desc — adjacency guaranteed, but a High-importance change in a late-alphabet category drops to the bottom of its section.
• order by changes.importance desc, changes.category — only groups changes that happen to share an importance. That is exactly the example in the description ("they have the same Priority"), but not the general case.
• Group by category, with the categories themselves ordered by their most important change — keeps important categories first and guarantees adjacency. See point 3 for why this one is expensive.

Which of the three do we actually want?

2. In what order should the categories themselves be listed?

ChangeClass.category is a DBListClass with an empty sql/classname, displayType=input and picker=1 — i.e. free text with autocomplete over whatever previous authors typed. So:

• there is no controlled vocabulary and no canonical order: "Repository", "Repository app" and "repository" are three distinct categories and would form three distinct groups;
• alphabetical is the only ordering available for free. If we want a meaningful order (say Macros before Repository), categories have to become a managed, ordered list, which is a change of its own and probably needs a migration of existing values.

Do we accept alphabetical, or do we first make categories a real ordered list?

3. Pagination constrains where the sort can happen

getChanges is now paginated (limit, default 100, and offset; it fetches one row beyond the page to detect a next page). The ordering therefore has to be fully expressible in the query, or a page can repeat or skip changes. Consequences:

• The third semantics above needs a per-category max(importance). The application deliberately never selects property values, because that requires programming right (see the comment on #getExistingVersions), and a correlated subquery in order by is beyond what XWQL translates.
• Computing it in Velocity instead would only group within the fetched page, so a category could still be split across two pages.

So that option is only realistic if we accept page-local grouping, or give the application another way to read the categories.

4. The section split in a release note page cuts across categories

releasenotechanges renders each audience as two independent getChanges calls:

• For Users and For Administrators: containsScreenshots="true", then a "Miscellaneous" list with containsScreenshots="false".
• For Developers: importance="Medium,High", then a "Miscellaneous" list with importance="Low".

Each call is sorted on its own, so a category with changes on both sides of a split appears twice — once in the main section and once under Miscellaneous. Is that acceptable (the split exists for prominence, so arguably yes), or should the grouping win over the split?

Related: should the Miscellaneous lists be grouped at all? For developers they are uniformly Low importance, so grouping there reduces to plain category order.

5. Should the category be visible?

None of the four displayers (Simple, List, Grid, Flow) renders the category — only a change's own page does, through ChangeSheet. Grouping alone therefore produces an adjacency the reader cannot explain. The description settles for "no heading", but should we at least display the category as a label on each change, or a heading per group, so that the grouping is perceivable?

6. Interaction with RN-40

RN-40 asks for entries sorted by creation date. Whatever is decided here has to compose with it — creation date as the tie-break within a category? Probably best decided together.

7. Scope

Should the grouping be unconditional in getChanges, which changes the output of every existing report including Code/Report, or an opt-in parameter (for instance groupBy="category") that the release note pages turn on?