Where to put supplementary docs?

[Andrew Haley]

Anyone?

On 4/22/25 10:31, Andrew Haley wrote:
> Sometimes, when reviewing a PR, we have supporting documents to
> justify a change. These docs can include diagrams, etc. In the past
> some such documents were put on the webrev server, and sometimes they
> got lost. One example of such a file is "Fast Subtype Checking in the
> HotSpot JVM," which explained the (now obsolete) secondary subtype
> checking algorithm.
> 
> Today, documents are sometimes uploaded to JIRA or attached to the PR
> itself. Sometimes they are stored in someone's personal web space, and
> linked from a PR, and that's when things get lost.
> 
> It would be better for long-term retention if such documents were
> included in the JDK repository itself, and committed to the repo as
> part of the PR. I'm assuming that these files will be fairly small, so
> will not greatly increase the size of the repo.
> 
> I propose to add a new subdirectory to jdk/doc, called "ref" or
> "reference". This is not for every possible reference document, but
> those that aid the maintainer and will be useful in the future. A
> comment in the source code should refer the reader to the appropriate
> reference document.
> 
> Does anyone here object to this? Is there some other place than
> "doc/ref" that would be more appropriate?
> 
> Thanks,
> 
> Andrew.
> 

-- 
Andrew Haley  (he/him)
Java Platform Lead Engineer
Red Hat UK Ltd. <https://www.redhat.com>
https://keybase.io/andrewhaley
EAC8 43EB D3EF DB98 CC77 2FAD A5CD 6035 332F A671