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-r...@openjdk.org> on behalf of
Michael Strauß <michaelstr...@gmail.com>
*Date: *Friday, August 9, 2024 at 07:31
*To: *
*Cc: *openjfx-dev@openjdk.org <openjfx-dev@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.goryac...@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
