Call for Discussion: New Project: Developer's Guide

[Jesper Wilhelmsson]

> On 20 Mar 2020, at 11:33, Magnus Ihse Bursie <magnus.ihse.bursie at oracle.com> wrote:
> 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,

Hi Magnus.

> 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.

From my earlier reply on this topic:
"There is a section for code conventions in the current guide. It's empty. I think a good start here [for the C++ code] could be to either link to John's JVM code conventions, or move that page into the guide. For the Java code there are several pages out there that could serve as a foundation, or just be linked to. However, I consider this implementation details that can be discussed once the project has been created and someone sets out to actually update those pages."

> 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.

Yes, there is much interest in getting a style guide in place so I'm sure this will be one of the first things that is brought up on the new mailing list once created.

> 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.

Andreas did reach out to me on this topic last week and will be in the loop once we get the project up and running.

One of the first things to do though, before we add a lot of new stuff, is to convert the existing material to some form of markdown and decide on a layout etc that works for a guide like this. I think your expertise in markdown and makefiles for such usage would come in very handy in that work ;-)

Thanks,
/Jesper

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