Call for Discussion: New Project: Developer's Guide

[Magnus Ihse Bursie]

On 2020-03-12 00:51, Jesper Wilhelmsson wrote:
> Hi.
>
> 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 [1] 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 [2], 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.

Hi Jesper,

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 [1]. 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.

/Magnus

[1] http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html