Where to put supplementary docs?

[Jesper Wilhelmsson]

Hi Andrew,

Documentation on individual changes should ideally be kept in JBS or in the PR. We can select one of them to promote as THE place to store stuff if that makes anything better, but both will in practice be used for discussions around changes regardless of what we promote. There is also a conceptual difference between what should be discussed where - the JBS issue discuss the problem, its cause, and potential solutions, while the PR discuss the particular solution implemented. If a PR is closed due to the implementation being rejected, only the part of the discussion related to that particular implementation should be lost. Anything generic that lead to the various choices made should still be there in JBS. This hints that JBS would be the better place for supporting documents unless they are extremely implementation specific. There might be arguments for other places but in my mind none strong enough to motivate a new solution in addition to what is already available.

Dalibor mentioned the wiki, this is a good place to store more in-depth descriptions of how things work in the codebase. Some might argue that the wiki is out of date and no-one keeps it updated when changes are made. I would argue that this is a problem with developers not knowing that the documentation exists or not caring enough about the documentation to update it, rather than a problem with where or how the documentation is stored. Archie already made this argument, regardless of where the documentation exists, a comment in the source code or in the PR/JBS issue referring to it would be extremely useful and would serve the same purpose regardless of document location.

If the JBS issue for the change and the wiki is not sufficient for some reason, we also have the concept of informational JEPs. An informational JEP can be created to host feature documentation or technical investigations. I would personally rather see this be an informational sub-task to the issue itself, but both are in JBS and can be easily linked from the issue.

We also have the CR server; https://openjdk.org/groups/web/crServer.html  This is storage supposed to be used for exactly this kind of documents and files. It was used a lot more in the past and I'm not sure if there are reasons to discourage its usage today, but it's still there for now at least.

The only place that should be banned, and that we all need to help remind other community members to not use, is the rest of the internet. Many OpenJDK developers work in companies with some form of security policy. Often these policies forbids the employees to download random files from ramdom places on the internet. Placing supporting files in such places, be it some personal server, blogs, other company websites, the internet, means that many of us can't access those files without violating such policies. Whenever someone links to a file somewhere else, the default reply should always be: "Please use existing OpenJDK infrastructure to store this information. Ask your Sponsor to help if you don't have the necessary permissions to do so yourself."

/Jesper


On 22 Apr 2025, at 11:31, Andrew Haley <aph-open at littlepinkcloud.com> 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.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jdk-dev/attachments/20250424/d441e7ff/attachment.htm>