Call for Discussion: New Project: Developer's Guide

[Jesper Wilhelmsson]

Hi John, Martijn, everyone.

The way I see it everyone can contribute in some way. We already have a lot of material that needs to be updated and converted to some form of markdown. There are also several missing parts that needs to be authored from scratch. Work done by people new to the project will of course have to be reviewed by those who have been here for a while, and I'm sure that work done by the experienced members of our community will also benefit from being reviewed by new members to catch parts and language that isn't obvious unless you have the background. I don't really think there is any big difference here compared to how we treat our source code. We wouldn't let a newcomer push code into the JDK without review, the same is true here, but still we appreciate any contributions made by new members of the community.

For this guide I'm personally more interested in process questions than code style. Taking code review as an example the guide should have examples of how to perform a review; currently using webrev, emails, etc. (Skara will likely change things a lot.) It should talk about the 24 hour rule and give examples of what might be considered a trivial change. Some of this is already covered by http://openjdk.java.net/contribute/ and there are pages in the Hotspot how-to [1] that covers this as well, so we'll see what will be considered useful for inclusion in the end. My hope is that the pages contained in the Hotspot how-to [1] and other pages spread on the wiki and in other places can be removed once we are done with the guide.

There is a section for code conventions in the current guide. It's empty. I think a good start here 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.

The question right now I think is more of the kind; Do we think it would be useful to have an up-to-date developer's guide, and do we think an OpenJDK project is the right way to do that work?

One concern that has been brought to my attention is that one OpenJDK project isn't normally entitled to dictate how other OpenJDK projects should work. This is clearly a valid concern but I think that if we stick to tutorials and how-to guides, these won't really dictate anything, just explain how to do things (at least in my mind there is a difference). Another option could of course be to move the guide into the JDK source tree and have the JDK project be responsible for its maintenance. I don't have a strong preference here, I just want to update the guide.

/Jesper

[1] https://wiki.openjdk.java.net/display/HotSpot/HotSpot+How+To

> On 13 Mar 2020, at 10:37, Martijn Verburg <martijnverburg at gmail.com> wrote:
> 
> Hi John,
> 
> I totally get where you are coming from and the intent of message, all good!
> 
> Our group will be happy to help Jesper et al in *whatever capacity he and
> the other experienced folks want us to*.
> 
> If that’s just reviewing drafts as newcomers or doing something like (dare
> I say it boring) formatting work then we will roll up sleeves and do just
> that ��.
> 
> Cheers,
> Martijn
> 
> 
> 
> On Fri, 13 Mar 2020 at 08:34, John Rose <john.r.rose at oracle.com> wrote:
> 
>> On Mar 12, 2020, at 11:04 PM, Florian Weimer <fw at deneb.enyo.de> wrote:
>>> 
>>> * John Rose:
>>> 
>>>> And I suggest the same to others who are responding
>>>> with a “count me in”.  This project will require (as
>>>> Liam Neeson might say) “a very particular set of skills,
>>>> …acquired over a very long career.”  It is not a starter
>>>> task, as far as I can tell.  However, I’ll give deference to
>>>> Jesper, who might have a different vision for this.
>>> 
>>> Wouldn't input from people not completely familiar with the processes
>>> be valuable, so that it becomes clearer what needs documenting?
>> 
>> That’s a very good point.  Must that input be obtained by recruiting
>> such people as project members, or can it be acquired via other
>> means such as questionnaires and experience reports?
>> 
>> Also, to be honest:  I missed the import of Jesper’s
>> initial statement, “Strict rules for OpenJDK development
>> are… outside of the scope of this project.”  I think this
>> means that vexed questions like code reviews and style
>> guides are off the table for now, which means the analogy
>> of a hospital policy committee is not nearly as applicable
>> as I thought it was.  My apologies!
>> 
>> A new person’s experience is precious and should
>> be captured quickly, before it is forgotten.  My first
>> response to Martijn didn’t do justice to this fact.
>> We old-timers have no clue anymore what we know
>> and how we learned it the first time; “how to learn
>> it” is the whole job of a new person—but they forget
>> quickly once they learn the ropes.  Watching this
>> over and over again, I have noticed that we have no
>> good way to capture those new-person experiences.
>> (Long-haul experiences, on the other hand, are
>> abundantly documented.  The problem there is it
>> goes stale after a few years.)  I’d be really interested
>> to hear from people who have seen successful capture
>> of information from new folks to improve on-boarding.
>> My best take on it is to have a place where new folks
>> can share what they are learning *when the experience
>> is fresh*, in such a way that their more experienced
>> team mates can use it as raw material for the next
>> revision of the on-boarding guide.
>> 
>> I wish there were an OpenJDK wiki which would be
>> immediately open to all OpenJDK authors, exactly
>> for this purpose, but our infra isn’t set up that way.
>> Imagine reading the experience reports of the last
>> ten years of new folks, explaining what went right
>> and wrong, and commenting on each others’
>> experience…  The closest thing we have to this is
>> email archives, which are disorganized, and the
>> cr.ojn pages, which are isolated (and not intended
>> for documentation, though useful for it nevertheless).
>> 
>> Regarding the parts of the guide which would be for
>> long-haul use (not on-boarding), a big problem is
>> extracting the information from people who have been
>> working with the existing practices for long enough to
>> know their good sides and bad sides.   There’s always
>> the problem of keeping such documentation fresh.
>> 
>> Also, I think such a guide should be more descriptive
>> than prescriptive.  (Today in a different thread I
>> talked about descriptive vs. prescriptive, in the setting
>> of a proposal for a new prescriptive code style enforced
>> by robots.)  The current proposal to avoid “strict” rules
>> would seem to avoid the risks of prescriptiveness, for now.
>> 
>> Is there a difference between “long haul” and “on-boarding”
>> documentation?  Yes, because they are for different audiences.
>> Every project demands that the new folks learn a bunch of
>> stuff before they do anything; hopefully it’s not too much
>> and it’s easy to learn, and then your apprenticeship begins.
>> Also, every project has a much larger set of best practices
>> and specifications which don’t need to be learned up front,
>> but which still shape the project as a whole.  No one person
>> knows them all at once, but people need to refer to them.
>> I’m talking about documentation like “how to do gatekeeping”
>> or “what are the bytecodes of the JVM”.  I would think
>> those would go into a dev-guide of some sort, but in a
>> different place than the important “how to get started”
>> sections.
>> 
>> I hope Jesper will have more comments on these puzzles.
>> 
>> — John
> 
> --
> Cheers, Martijn (Sent from Gmail Mobile)