The release notes for each version are currently independently available at https://cmake.org/cmake/help/latest/release/index.html
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
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:
- opening release notes page for recent version and searching through them
- 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):
- 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.