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
