From jwilhelm at openjdk.org Wed Apr 2 22:33:06 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Wed, 2 Apr 2025 22:33:06 GMT Subject: RFR: Replace affects_versions.png with SVG [v3] In-Reply-To: References: <2EVDtsXtXKolQJ6k6ef9gy64Su5EpyuV9bI73LGTAdw=.7d04b867-59f1-4f01-9687-42828fcda22a@github.com> Message-ID: On Thu, 20 Mar 2025 17:07:12 GMT, Alexey Ivanov wrote: >> Replace `affects_versions.png` with Scalable Vector Graphics (SVG) image. >> >>

PNG vs SVG

>> >> **PNG:**\ >> ![affects_versions.png](https://github.com/openjdk/guide/blob/be88a6debcb0dfb7f8fb0e8f3e95ff35950ca9c4/src/images/affects_versions.png?raw=true) >> >> **SVG:**\ >> ![affects_versions.svg](https://raw.githubusercontent.com/aivanov-jdk/dev-guide/bc65ea67251cc68360fc746a77200d8c93fd78b5/src/images/affects_versions.svg) >>

PNG vs SVG

>> >> SVG is crisper, especially on High DPI monitors, its size is much smaller (1.04 KB vs 26.24 KB), it's easier to edit and the edit history is preserved. > > Alexey Ivanov has updated the pull request incrementally with one additional commit since the last revision: > > End 12-na with circle @aivanov-jdk Your change (at version c48bff06cc94e1b55b9db68257b2a2d9f85a9fef) is now ready to be sponsored by a Committer. ------------- PR Comment: https://git.openjdk.org/guide/pull/147#issuecomment-2775484994 From smarks at openjdk.org Wed Apr 9 21:32:53 2025 From: smarks at openjdk.org (Stuart Marks) Date: Wed, 9 Apr 2025 21:32:53 GMT Subject: RFR: Add material about updating the CSR when a backout occurs. Message-ID: Also, add a small fix to the Makefile. ------------- Commit messages: - Add material about updating the CSR when a backout occurs. Changes: https://git.openjdk.org/guide/pull/148/files Webrev: https://webrevs.openjdk.org/?repo=guide&pr=148&range=00 Stats: 6 lines in 2 files changed: 5 ins; 0 del; 1 mod Patch: https://git.openjdk.org/guide/pull/148.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/148/head:pull/148 PR: https://git.openjdk.org/guide/pull/148 From jwilhelm at openjdk.org Wed Apr 9 21:52:39 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Wed, 9 Apr 2025 21:52:39 GMT Subject: RFR: Add material about updating the CSR when a backout occurs. In-Reply-To: References: Message-ID: On Wed, 9 Apr 2025 21:28:38 GMT, Stuart Marks wrote: > Also, add a small fix to the Makefile. Thank you for adding this! Looks good! src/guide/testing-the-jdk.md line 339: > 337: > 338: To backout a change with git, use `git revert`. This will apply (commit) the anti-delta of the change. > 339: Then proceed as usual with creating a PR and getting it reviewed. For consistency I'd prefer if this sentence was on the same line as the previous, since this is not a new paragraph. Not critical, but if you have the extra time :-) ------------- Marked as reviewed by jwilhelm (Lead). PR Review: https://git.openjdk.org/guide/pull/148#pullrequestreview-2754882687 PR Review Comment: https://git.openjdk.org/guide/pull/148#discussion_r2036187238 From aivanov at openjdk.org Wed Apr 9 21:56:42 2025 From: aivanov at openjdk.org (Alexey Ivanov) Date: Wed, 9 Apr 2025 21:56:42 GMT Subject: Integrated: Replace affects_versions.png with SVG In-Reply-To: <2EVDtsXtXKolQJ6k6ef9gy64Su5EpyuV9bI73LGTAdw=.7d04b867-59f1-4f01-9687-42828fcda22a@github.com> References: <2EVDtsXtXKolQJ6k6ef9gy64Su5EpyuV9bI73LGTAdw=.7d04b867-59f1-4f01-9687-42828fcda22a@github.com> Message-ID: <8jp4BQVcvBnyJ6s0J-A0vr16cinWh2ZAU3MjDYa7hi0=.213a87e8-c491-4e8f-a299-1da812614b49@github.com> On Fri, 14 Mar 2025 16:04:56 GMT, Alexey Ivanov wrote: > Replace `affects_versions.png` with Scalable Vector Graphics (SVG) image. > >

PNG vs SVG

> > **PNG:**\ > ![affects_versions.png](https://github.com/openjdk/guide/blob/be88a6debcb0dfb7f8fb0e8f3e95ff35950ca9c4/src/images/affects_versions.png?raw=true) > > **SVG:**\ > ![affects_versions.svg](https://raw.githubusercontent.com/aivanov-jdk/dev-guide/bc65ea67251cc68360fc746a77200d8c93fd78b5/src/images/affects_versions.svg) >

> > SVG is crisper, especially on High DPI monitors, its size is much smaller (1.04 KB vs 26.24 KB), it's easier to edit and the edit history is preserved. This pull request has now been integrated. Changeset: b10cd0da Author: Alexey Ivanov Committer: Jesper Wilhelmsson URL: https://git.openjdk.org/guide/commit/b10cd0da8178361841861a24dee0711204883ef8 Stats: 164 lines in 3 files changed: 163 ins; 0 del; 1 mod Replace affects_versions.png with SVG Reviewed-by: ihse, jwilhelm, iris ------------- PR: https://git.openjdk.org/guide/pull/147 From smarks at openjdk.org Wed Apr 9 21:58:52 2025 From: smarks at openjdk.org (Stuart Marks) Date: Wed, 9 Apr 2025 21:58:52 GMT Subject: RFR: Add material about updating the CSR when a backout occurs. [v2] In-Reply-To: References: Message-ID: > Also, add a small fix to the Makefile. Stuart Marks has updated the pull request incrementally with one additional commit since the last revision: Keep paragraph as a single line (per Jesper). ------------- Changes: - all: https://git.openjdk.org/guide/pull/148/files - new: https://git.openjdk.org/guide/pull/148/files/a9f26da3..cfdad340 Webrevs: - full: https://webrevs.openjdk.org/?repo=guide&pr=148&range=01 - incr: https://webrevs.openjdk.org/?repo=guide&pr=148&range=00-01 Stats: 2 lines in 1 file changed: 0 ins; 1 del; 1 mod Patch: https://git.openjdk.org/guide/pull/148.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/148/head:pull/148 PR: https://git.openjdk.org/guide/pull/148 From smarks at openjdk.org Wed Apr 9 21:58:52 2025 From: smarks at openjdk.org (Stuart Marks) Date: Wed, 9 Apr 2025 21:58:52 GMT Subject: RFR: Add material about updating the CSR when a backout occurs. [v2] In-Reply-To: References:

Message-ID: On Wed, 9 Apr 2025 21:49:25 GMT, Jesper Wilhelmsson wrote: >> Stuart Marks has updated the pull request incrementally with one additional commit since the last revision: >> >> Keep paragraph as a single line (per Jesper). > > src/guide/testing-the-jdk.md line 339: > >> 337: >> 338: To backout a change with git, use `git revert`. This will apply (commit) the anti-delta of the change. >> 339: Then proceed as usual with creating a PR and getting it reviewed. > > For consistency I'd prefer if this sentence was on the same line as the previous, since this is not a new paragraph. Not critical, but if you have the extra time :-) Can do. I want to wait for a review from @jddarcy as well. ------------- PR Review Comment: https://git.openjdk.org/guide/pull/148#discussion_r2036190058 From darcy at openjdk.org Wed Apr 9 22:05:48 2025 From: darcy at openjdk.org (Joe Darcy) Date: Wed, 9 Apr 2025 22:05:48 GMT Subject: RFR: Add material about updating the CSR when a backout occurs. [v2] In-Reply-To: References:

Message-ID: On Wed, 9 Apr 2025 21:58:52 GMT, Stuart Marks wrote: >> Also, add a small fix to the Makefile. > > Stuart Marks has updated the pull request incrementally with one additional commit since the last revision: > > Keep paragraph as a single line (per Jesper). Marked as reviewed by liach (no project role). ------------- PR Review: https://git.openjdk.org/guide/pull/148#pullrequestreview-2754904425 From smarks at openjdk.org Wed Apr 9 22:26:41 2025 From: smarks at openjdk.org (Stuart Marks) Date: Wed, 9 Apr 2025 22:26:41 GMT Subject: Integrated: Add material about updating the CSR when a backout occurs. In-Reply-To: References: Message-ID: On Wed, 9 Apr 2025 21:28:38 GMT, Stuart Marks wrote: > Also, add a small fix to the Makefile. This pull request has now been integrated. Changeset: 71fbb94b Author: Stuart Marks URL: https://git.openjdk.org/guide/commit/71fbb94b0b7b3ca75869bc158805971a3fe3d3df Stats: 6 lines in 2 files changed: 4 ins; 0 del; 2 mod Add material about updating the CSR when a backout occurs. Reviewed-by: jwilhelm, darcy, liach ------------- PR: https://git.openjdk.org/guide/pull/148 From aph-open at littlepinkcloud.com Tue Apr 22 09:31:19 2025 From: aph-open at littlepinkcloud.com (Andrew Haley) Date: Tue, 22 Apr 2025 10:31:19 +0100 Subject: Where to put supplementary docs? Message-ID: 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. From archie.cobbs at gmail.com Tue Apr 22 14:34:12 2025 From: archie.cobbs at gmail.com (Archie Cobbs) Date: Tue, 22 Apr 2025 09:34:12 -0500 Subject: Where to put supplementary docs? In-Reply-To: References: Message-ID: On Tue, Apr 22, 2025 at 4:31?AM Andrew Haley wrote: > 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. I support this idea. I'm sure in lots of other places too, but in the compiler, there is often subtle or non-obvious logic happening that could benefit from a more proper explanation than what you get from inline comments, etc. The hard part is keeping this documentation up-to-date as the code evolves. If the docs are not sitting in the same directory as the code they document, then there probably needs to be some other trick to remind people to keep them in sync e.g., a big comment at the top of the file like /* REFERENCE DOCUMENTATION HERE: KEEP UP TO DATE */ or something. Even better, add a skara check that mechanically verifies, for any change to a source file, either (a) there is no corresponding reference documentation or (b) that documentation has been updated (perhaps with just a trivial date/counter bump if no real change was needed), etc. Then the documentation updates would be naturally included as part of PR reviews. -Archie -- Archie L. Cobbs -------------- next part -------------- An HTML attachment was scrubbed... URL: From jwilhelm at openjdk.org Wed Apr 23 17:07:41 2025 From: jwilhelm at openjdk.org (Jesper Wilhelmsson) Date: Wed, 23 Apr 2025 17:07:41 GMT Subject: RFR: Updated AffectsVersion image Message-ID: Updated image to make case 5 look more like the previous cases. Also fixed a borken link. ------------- Commit messages: - Arrows look weird on github - Update AffectsVersion image Changes: https://git.openjdk.org/guide/pull/149/files Webrev: https://webrevs.openjdk.org/?repo=guide&pr=149&range=00 Stats: 505 lines in 2 files changed: 372 ins; 0 del; 133 mod Patch: https://git.openjdk.org/guide/pull/149.diff Fetch: git fetch https://git.openjdk.org/guide.git pull/149/head:pull/149 PR: https://git.openjdk.org/guide/pull/149 From aph-open at littlepinkcloud.com Thu Apr 24 09:10:04 2025 From: aph-open at littlepinkcloud.com (Andrew Haley) Date: Thu, 24 Apr 2025 10:10:04 +0100 Subject: Where to put supplementary docs? In-Reply-To: References: Message-ID: 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://keybase.io/andrewhaley EAC8 43EB D3EF DB98 CC77 2FAD A5CD 6035 332F A671 From jesper.wilhelmsson at oracle.com Thu Apr 24 12:31:38 2025 From: jesper.wilhelmsson at oracle.com (Jesper Wilhelmsson) Date: Thu, 24 Apr 2025 12:31:38 +0000 Subject: Where to put supplementary docs? In-Reply-To: References: Message-ID: <4B094F68-914C-4B68-A0A7-6137909679FD@oracle.com> 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 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: From rehn at rivosinc.com Thu Apr 24 15:26:50 2025 From: rehn at rivosinc.com (Robbin Ehn) Date: Thu, 24 Apr 2025 17:26:50 +0200 Subject: Where to put supplementary docs? In-Reply-To: References:

Message-ID: Hi, I agree. I suggested co-located docs in some less public forums in the past. One major challenge with the other places (CR, JBS, PR, wiki), is that they don't handle versioning. (naturally) This means the code can't safely refer to, e.g., a wiki page, as that page may describe a newer version. If a developer is working in JDK 11 or in the Loom project, they need the relevant documentation for that specific fork/branch. JBS/PR also have the issue that they primarily describe the original bug/patch. The code integrated can change significantly during the PR's lifetime, and one may need to read many comments in the PR/JBS to figure things out. Additionally, many developers 'grep' the code, which means co-located documentation is very easy to find (and thus easier to keep up-to-date or add new docs to). A concrete example: https://wiki.openjdk.org/display/HotSpot/Synchronization If you are hunting a bug in JDK 11, this page may be of value. If you want to know how locking works in JDK 25, you shouldn't be reading this page. Co-locating the docs with the code helps with these issues. /Robbin On Thu, Apr 24, 2025 at 11:11?AM Andrew Haley wrote: > > 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://keybase.io/andrewhaley > EAC8 43EB D3EF DB98 CC77 2FAD A5CD 6035 332F A671 > From mark.reinhold at oracle.com Fri Apr 25 19:41:10 2025 From: mark.reinhold at oracle.com (Mark Reinhold) Date: Fri, 25 Apr 2025 19:41:10 +0000 Subject: Where to put supplementary docs? In-Reply-To: References:

Message-ID: <20250425154110.11559658@eggemoggin.niobe.net> 2025/4/24 11:26:50 -0400, Robbin Ehn : > Hi, I agree. > > I suggested co-located docs in some less public forums in the past. > > One major challenge with the other places (CR, JBS, PR, wiki), is that > they don't handle versioning. (naturally) This means the code can't > safely refer to, e.g., a wiki page, as that page may describe a newer > version. If a developer is working in JDK 11 or in the Loom project, > they need the relevant documentation for that specific fork/branch. > > JBS/PR also have the issue that they primarily describe the original > bug/patch. The code integrated can change significantly during the > PR's lifetime, and one may need to read many comments in the PR/JBS to > figure things out. > > Additionally, many developers 'grep' the code, which means co-located > documentation is very easy to find (and thus easier to keep up-to-date > or add new docs to). > > A concrete example: https://wiki.openjdk.org/display/HotSpot/Synchronization > If you are hunting a bug in JDK 11, this page may be of value. > If you want to know how locking works in JDK 25, you shouldn't be > reading this page. > > Co-locating the docs with the code helps with these issues. My initial internal reaction to Andrew?s proposal was, ?meh, yet another place to search for documents?? But Robbin makes a good point: If what we?re talking about here is documentation of JDK internals then that?s inherently version-specific. Keeping such documentation anywhere else just invites it to get stale and out of date, in addition to making it harder to find. Jesper makes some good points, too, in his survey of the alternatives, though I don?t agree with all of them. Some commentary: - JBS doesn?t support markup in non-JEP/CSR issues, and we?re unlikely to change that. This makes it difficult to maintain longer documents there. A nice side benefit of placing them in the repo is that we can use Markdown, and GitHub will render them. - JBS issues (and GitHub PRs) can be hard to discover. To take Andrew?s example of the old HotSpot subtype-checking algorithm, if you wanted to know more about that then how would you find it in JBS? Yet a quick search of `doc/ref/hotspot` would turn it up quickly. - Wikis are where information goes to die. Sorry. (Plus, the markup language is worse than horrid.) - Informational JEPs are under-used, but given that these documents are version-tied, informational JEPs are not a great solution. - The trouble with cr.openjdk.org, as Andrew pointed out, is that a document posted there today is not guaranteed to be there tomorrow, or next month, or next year. People shuffle their personal content there all the time. - I totally agree that all OpenJDK-related documentation should be maintained and published in OpenJDK infrastructure. If we do go ahead with Andrew?s proposal then it will be critical to crisply define what this directory for, lest it become a dumping ground for documents that really belong elsewhere, or mistaken for a collection of documents meant for non-contributors. ?Reference documentation for JDK internals? seems like a good start, which also suggests that `doc/internals` might be a better name than `doc/ref`. - Mark