Call for Discussion: New Project: Developer's Guide

[Lars Francke]

On Fri, Mar 13, 2020 at 2:30 PM Jesper Wilhelmsson <
jesper.wilhelmsson at oracle.com> wrote:

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

As someone who tried to get a patch in for the first time last year: Yes,
that'd be incredibly helpful. There's lots of information out there, some
is _clearly_ outdated and marked as such, other things are outdated but not
marked again others seem up-to-date but to distinguish them from each other
is hard if you know nothing.

So I'd be happy to review things as well from the complete newcomer
perspective.


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