RFR: 8357000: Write overview documentation for start of release changes [v2]

[Mark Reinhold]

On Tue, 20 May 2025 17:14:38 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> First attempt to populate "supplementary docs" with a discussion of the start of release changes. For reference on the idea of supplementary docs, see the thread
>> 
>> "Where to put supplementary docs?"
>> https://mail.openjdk.org/pipermail/jdk-dev/2025-April/009975.html
>
> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Respond to review feedback.

Writing this up is good, but I think it belongs in `doc` rather than `doc/ref`. In discussion, the latter morphed into `doc/internals`, and this isn’t about JDK internals. Also, this fits well alongside the `building.md` and `testing.md` files already in `doc`. (Which suggests that a name that’s a gerund might fit even better — `starting-next-release.md`? — for extra credit.)

Consider framing the whole document as “how to prepare for the next release,” with explicit instructions on what to do. The present lists of concepts, and of files and changes, comes across more as your personal notes rather than a list of instructions for someone to follow.

doc/ref/start-of-release.md line 3:

> 1: % Explanation of start of release changes
> 2: 
> 3: ## Overview

Is there just one section, titled "Overview", or will there be more? If the former, consider omitting this heading.

doc/ref/start-of-release.md line 17:

> 15: * Highest `-source`/`-target'/`--release` argument recognized by `javac`
> 16: 
> 17: In more detail, updated files include:

The phrasing here, "... updated files include", suggests that this will just be a list of files, but in fact it's a list of files and instructions for updating them.

-------------

Changes requested by mr (Lead).

PR Review: https://git.openjdk.org/jdk/pull/25317#pullrequestreview-2858664833
PR Review Comment: https://git.openjdk.org/jdk/pull/25317#discussion_r2100868110
PR Review Comment: https://git.openjdk.org/jdk/pull/25317#discussion_r2100870143