Call for Discussion: New Project: Developer's Guide
Magnus Ihse Bursie
magnus.ihse.bursie at oracle.com
Fri Mar 20 10:33:42 UTC 2020
On 2020-03-12 00:51, Jesper Wilhelmsson wrote:
> I would like to discuss the possible creation of the Developer's Guide Project
> with myself, Jesper Wilhelmsson, as the lead and the Core-Libs, Compiler, and
> Hotspot groups as the sponsoring Groups.
> The initial goal of the project would be to create up-to-date guidelines for
> OpenJDK development and contributions. The intent is to update the existing
> OpenJDK Developer's Guide  which hasn't been updated since 2012. Parts of
> the existing guide are in need of updates while other parts are yet to be
> written. The initial source code for this project will be based on the current
> OpenJDK Developer's Guide.
> In more recent years some process related information has been published on the
> OpenJDK wiki , but this information was never reviewed or approved by the
> community. Even though large parts of this information may be accurate, it needs
> to go through proper review before it can be seen as official guidelines for
> OpenJDK development.
> Once the initial goal has been reached the project will transition into a
> maintenance project to keep the OpenJDK Developer's Guide up to date.
> The OpenJDK Developer's Guide is intended to contain tutorial style texts that
> give examples and step-by-step directions for common parts of the development
> process. Strict rules for OpenJDK development are better suited to a process
> JEP. The development of such a JEP is outside of the scope of this project but
> will be developed as part of a separate effort in parallel.
I've browsed through the discussion, but could not easily find if you
consider style guides (this neverending hot topic!) as being included
in, or excluded from, this effort.
Personally, as a newcomer to any project, I would consider a style guide
helpful when trying to submit code that'd be readily accepted. Even if
it's just a "descriptive" guide, not a normative one. So, given this,
I'd strongly recommend that the project ends up with promoting a single
source of truth style guide, even if it is just descriptive of most
current practices, rather than normative.
And, in that respect, I'd kindly want to point out the effort made by
Andreas Lundblad some years ago . His style guide went through
multiple iterations, incorporated a lot of feedback from many OpenJDK
developers, and is probably the best document to capture the current
"best practices" of OpenJDK source code style. Unfortunately, it
basically fell short of the finishing line since there were no good way,
process-wise, on how to handle the resulting document.
More information about the discuss