Consolidated page for organizing release notes

The release notes for each version are currently independently available at

Question: How we we feel about adding a condolidated page with all the release notes aggregated ?

  • Provide both consolidated & per-version release notes
  • Only provide consolidated release notes
0 voters

cc: @craig.scott @marc.chevrier @brad.king


When I am not sure about the exact version introducing a specific feature or fix, I often end up doing one of these:

  1. opening release notes page for recent version and searching through them
  2. locally searching through the directory CMake/Help/release of the source tree

This post discuss how to improve the status quo to provide a more useful release notes page.

I can see advantages of both. If we do change to a consolidated set of release notes, we would want to have an index at the top for easy navigation. The policies page is a consolidated summary page, and sometimes I find it to be getting harder to work with as it grows longer. I also find it useful to be able to scan the full list of policies though, so I expect we’d have a similar situation with the release notes.

I would like both. If the consolidated is collated by version, it is less useful than the per-version ones (e.g., if I’m looking for what I can do in that version). But if it is grouped more like an index (using Markdown because I can never remember reST syntax without highlighting support):

## Ninja

- support for Fortran (since 3.X)
- support for job pools (since 3.Y)
- optimized dependencies (since 3.Z)

then I can use it to see for each category what version I might want to target.

I would like to see the addition of a consolidated page while also keeping the paginated version that we have right now, in order to get the best of both worlds.

Here’s an example of a consolidated page which also provides a table of contents in the sidebar to aid navigation:

Because the table of contents is in a sidebar, it doesn’t scroll when you scroll the main body, so it always remains easily accessible.