Where to put supplementary docs?

[Jesper Wilhelmsson]

On 28 Apr 2025, at 17:28, Mark Reinhold <mark.reinhold at oracle.com> wrote:

2025/4/28 6:33:20 -0400, magnus.ihse.bursie at oracle.com:
...

I don't think we need to overthink this. Is there anything stopping
anyone from starting to use this straight away? Any kind of additional
structures/guidelines etc can be added later on, if this turns out to be
so well-used it gets overcrowded.

Do we need to overthink this?  No.

But any proposal for a new convention for all of JDK development,
if it is to succeed, needs at least a rough consensus behind it.

I don’t, so far, see such a consensus.

This discussion seems to have taken a turn towards a different type of documentation than what I interpreted the initial question was about. When I read "supporting documents to
justify a change", that's what I replied to. I still think these would be best off attached to the JBS issue. I would not like to see various spreadsheet files with benchmark data or images with graphs etc committed to the source code.

If we talk about descriptions of how the code is implemented, documentation for developers who need to understand subsystems in order to work on the code, then yes, I think it's totally reasonable to have that in markdown files in the source tree.

At least in my mind these are two different types of documents. Sorry if that's just me :-)
/Jesper

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