On Tue, 20 May 2025 17:14:38 GMT, Joe Darcy <da...@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

Reply via email to