<!DOCTYPE html><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
As Andy mentioned, a JEP has value as documentation beyond the
moment a feature is implemented. It describes a a medium to large
feature, and is intended to be complete and accurate at the time
that feature is delivered. In the JDK, each release has a list of
JEPs that describe the feature set of that release. For example,
here is the list for the soon-to-be-released JDK 23:<br>
<br>
<a class="moz-txt-link-freetext" href="https://openjdk.org/projects/jdk/23/#Features">https://openjdk.org/projects/jdk/23/#Features</a><br>
<br>
Typically, a feature JEP is not updated after the release in which
the feature was delivered. If there are further refinements to a
feature, that's fine; it doesn't invalidate the original JEP.
Subsequent changes might or might not need a new JEP, depending on
how substantial the change.<br>
<br>
So the question is: Where should we store and track JavaFX JEPs? I
think we have three reasonable alternatives, with a couple
variations of the second.<br>
<br>
Alternative 1: In JBS, using the JEP issue type.<br>
<br>
This is where the JDK stores their JEPs.<br>
<br>
Pros:<br>
-- Uses the same mechanisms as the JDK does<br>
-- JEP issue can be easily linked to the Enhancement that will
implement it.<br>
<br>
Cons:<br>
-- Cumbersome to evolve, review, and track changes<br>
-- JIRA supports a more limited markdown than GitHub<br>
-- Because we aren't bundled, all JEPs would remain in Draft mode,
we would need other means (maybe labels) to indicate when a JEP was
considered to be final<br>
<br>
<br>
Alternative 2: In a git repository, using a markdown file<br>
<br>
JEPs would be reviewed and eventually integrated in an openjdk
repository. There are two variations we could consider:<br>
<br>
A. In the mainline openjdk/jfx repo (e.g., under "doc-files/jeps")<br>
<br>
B. In a separate "jfx-docs" repo<br>
<br>
In either case, we would need to create a separate JBS issue, with a
convention that would allow is to identify it as a JEP doc, to
integrate the JEP markdown file, once it was "accepted". We would
integrate that with a separate PR ahead of the implementation of
that JEP; for variation A it would be possible for the JEP to
accompany the implementation of the JEP in the same PR that
implements it, but I don't think that's a best practice (and I'd
still want a separate "JEP doc" issue). Having a separate repo
(variation B) more closely tracks the idea of JEPs being a separate
deliverable, but it's a little more overhead, and is perhaps less
flexible.<br>
<br>
Pros:<br>
-- Easier to evolve, review and track changes: Use a PR to review
the JEP<br>
-- Richer markdown<br>
<br>
Cons:<br>
-- Divergent with what the JDK does<br>
-- A PR in the same repo for the JEP and the feature itself could be
confusing (need to develop some "best practices")<br>
<br>
<br>
Alternative 3: On a Wiki page<br>
<br>
We could use a set of pages in the OpenJDK Wiki, one per JEP plus
an index page to organize them.<br>
<br>
Pros:<br>
-- A little easier to edit than a JBS issue, a little easier to
track changes (Wiki history diffs are at least somewhat easier to
read than raw JIRA diffs)<br>
<br>
Cons:<br>
-- Harder to organize<br>
-- Yet another editing tool to learn<br>
-- Harder to track the state without some conventions to cross-link
the JEP page in the Wiki to the JBS enhancement<br>
-- Harder to review than an MD file (no inline comments, although
that's true of JBS as well)<br>
<br>
<br>
Regardless of which alternative we choose, we will want to list the
JEPs for each release on a Wiki page, along with the JEPs that are
in progress. We should consider highlighting them in the release
notes.<br>
<br>
Comments?<br>
<br>
-- Kevin<br>
<br>
<br>
<div class="moz-cite-prefix">On 8/9/2024 8:28 AM, Andy Goryachev
wrote:<br>
</div>
<blockquote type="cite" cite="mid:BL3PR10MB61850070D0037F6824C85FF8E5BA2@BL3PR10MB6185.namprd10.prod.outlook.com">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style>@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}@font-face
{font-family:Aptos;
panose-1:2 11 0 4 2 2 2 2 2 4;}@font-face
{font-family:"Iosevka Fixed SS16";
panose-1:2 0 5 9 3 0 0 0 0 4;}@font-face
{font-family:"Times New Roman \(Body CS\)";
panose-1:2 11 6 4 2 2 2 2 2 4;}p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:10.0pt;
font-family:"Aptos",sans-serif;}a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}span.EmailStyle19
{mso-style-type:personal-reply;
font-family:"Iosevka Fixed SS16";
color:windowtext;}.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;
mso-ligatures:none;}div.WordSection1
{page:WordSection1;}</style>
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">Michael:<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">Yes,
by design. I think the JEPs still have value even after the
actual changes were made. Also, nothing prevents us from
creating an index.html file that lists the JEPs in
chronological order and mentions the state of the
implemented features and whether and how the actual
implementation differs from the JEP.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">Sorry,
I did not quite understand what you mean by "documentation
colocated with the code" - isn't that what I am proposing?<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">At
the same time, I wanted to consider other possibilities,
such as<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">-
wikis (same drawbacks as github PRs, even harder to review /
keep track of changes / lack of co-location)<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">-
separate doc repo (not co-located with the code)<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">- ??<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">What
do you think?<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">-andy<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<div id="mail-editor-reference-message-container">
<div>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal" style="margin-bottom:12.0pt"><b><span style="font-size:12.0pt;color:black">From:
</span></b><span style="font-size:12.0pt;color:black">openjfx-dev
<a class="moz-txt-link-rfc2396E" href="mailto:openjfx-dev-retn@openjdk.org"><openjfx-dev-retn@openjdk.org></a> on behalf of
Michael Strauß <a class="moz-txt-link-rfc2396E" href="mailto:michaelstrau2@gmail.com"><michaelstrau2@gmail.com></a><br>
<b>Date: </b>Friday, August 9, 2024 at 07:31<br>
<b>To: </b><br>
<b>Cc: </b><a class="moz-txt-link-abbreviated" href="mailto:openjfx-dev@openjdk.org">openjfx-dev@openjdk.org</a>
<a class="moz-txt-link-rfc2396E" href="mailto:openjfx-dev@openjdk.org"><openjfx-dev@openjdk.org></a><br>
<b>Subject: </b>Re: No Place for JEPs<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:11.0pt">Hi
Andy,<br>
<br>
wouldn't these documents risk getting outdated when
the codebase is<br>
evolved? JEPs seem to be most relevant at the time
when a feature is<br>
proposed. I think I'd rather have documentation
colocated with the<br>
code itself, this makes it easier to keep the
documentation in sync<br>
with the actual implementation.<br>
<br>
<br>
On Wed, Aug 7, 2024 at 8:46</span><span style="font-size:11.0pt;font-family:"Arial",sans-serif"> </span><span style="font-size:11.0pt">PM Andy Goryachev
<a class="moz-txt-link-rfc2396E" href="mailto:andy.goryachev@oracle.com"><andy.goryachev@oracle.com></a> wrote:<br>
><br>
> Dear fellow developers:<br>
><br>
><br>
><br>
> We often create JEPs and JEP-formatted documents
as we propose and develop new features. These help us
during the review process and I am sure are of some
benefit for application developers as they try to
learn the new functionality in depth. Presently,
we've been creating these files in personal
repositories, or presented as descriptions for pull
requests, see for example [0].<br>
><br>
><br>
><br>
> I think there is a value in making these
documents a part of the main repository, maybe under
/doc-files. Doing so would help with the review
process as the markdown files are both human-readable
and easily diff'ed. Also, I think it might be more
convenient to keep them in the same repo as the code,
as opposed to the some personal repositories or wikis.<br>
><br>
><br>
><br>
> What do you think?<br>
><br>
><br>
><br>
> -andy<br>
><br>
><br>
><br>
><br>
><br>
> References<br>
><br>
><br>
><br>
> [0] <a href="https://github.com/openjdk/jfx/pull/1522" moz-do-not-send="true" class="moz-txt-link-freetext">https://github.com/openjdk/jfx/pull/1522</a><o:p></o:p></span></p>
</div>
</div>
</div>
</div>
</blockquote>
<br>
</body>
</html>