No Place for JEPs

[Andy Goryachev]

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/20240809/d5755b18/attachment.htm>