No Place for JEPs

[Kevin Rushforth]

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:

https://openjdk.org/projects/jdk/23/#Features

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.

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.

Alternative 1: In JBS, using the JEP issue type.

This is where the JDK stores their JEPs.

Pros:
-- Uses the same mechanisms as the JDK does
-- JEP issue can be easily linked to the Enhancement that will implement it.

Cons:
-- Cumbersome to evolve, review, and track changes
-- JIRA supports a more limited markdown than GitHub
-- 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


Alternative 2: In a git repository, using a markdown file

JEPs would be reviewed and eventually integrated in an openjdk 
repository. There are two variations we could consider:

A. In the mainline openjdk/jfx repo (e.g., under "doc-files/jeps")

B. In a separate "jfx-docs" repo

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.

Pros:
-- Easier to evolve, review and track changes: Use a PR to review the JEP
-- Richer markdown

Cons:
-- Divergent with what the JDK does
-- A PR in the same repo for the JEP and the feature itself could be 
confusing (need to develop some "best practices")


Alternative 3:  On a Wiki page

We could use a set of  pages in the OpenJDK Wiki, one per JEP plus an 
index page to organize them.

Pros:
-- 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)

Cons:
-- Harder to organize
-- Yet another editing tool to learn
-- Harder to track the state without some conventions to cross-link the 
JEP page in the Wiki to the JBS enhancement
-- Harder to review than an MD file (no inline comments, although that's 
true of JBS as well)


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.

Comments?

-- Kevin


On 8/9/2024 8:28 AM, Andy Goryachev wrote:
>
> Michael:
>
> 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.
>
> Sorry, I did not quite understand what you mean by "documentation 
> colocated with the code" - isn't that what I am proposing?
>
> At the same time, I wanted to consider other possibilities, such as
>
> - wikis (same drawbacks as github PRs, even harder to review / keep 
> track of changes / lack of co-location)
>
> - separate doc repo (not co-located with the code)
>
> - ??
>
> What do you think?
>
> -andy
>
> *From: *openjfx-dev <openjfx-dev-retn at openjdk.org> on behalf of 
> Michael Strauß <michaelstrau2 at gmail.com>
> *Date: *Friday, August 9, 2024 at 07:31
> *To: *
> *Cc: *openjfx-dev at openjdk.org <openjfx-dev at openjdk.org>
> *Subject: *Re: No Place for JEPs
>
> Hi Andy,
>
> wouldn't these documents risk getting outdated when the codebase is
> evolved? JEPs seem to be most relevant at the time when a feature is
> proposed. I think I'd rather have documentation colocated with the
> code itself, this makes it easier to keep the documentation in sync
> with the actual implementation.
>
>
> On Wed, Aug 7, 2024 at 8:46 PM Andy Goryachev 
> <andy.goryachev at oracle.com> wrote:
> >
> > Dear fellow developers:
> >
> >
> >
> > 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].
> >
> >
> >
> > 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.
> >
> >
> >
> > What do you think?
> >
> >
> >
> > -andy
> >
> >
> >
> >
> >
> > References
> >
> >
> >
> > [0] https://github.com/openjdk/jfx/pull/1522
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20240820/af18c9f8/attachment-0001.htm>