RFR: Updated section on Code Conventions.

[mark.reinhold at oracle.com]

2020/6/26 15:42:30 -0700, alex.buckley at oracle.com:
> The CfV for the Developer's Guide Project said: "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."
> 
> With that in mind, some thoughts:
> 
> 1. The OpenJDK Bylaws define "social infrastructure" -- roles, voting, 
> groups, projects. Where is the definition of "technical infrastructure" 
> -- repositories, bug trackers, mailing lists, test fleets? Answer: 
> Locked up in the current OpenJDK Developer's Guide. It seems to me that 
> a good start would be: throw all the chapters in the current Guide up in 
> the air, and catch only the ones which let you write a dry, factual 
> manual about the technical infrastructure. Such a manual relies on the 
> social infrastructure from the Bylaws, notably the idea of a Project. 
> The manual is not "normative" in the sense of "using wise judgment to 
> establish a standard that people must follow". Accordingly, it does not 
> describe processes (e.g. CSR) or conventions (e.g. code style, or 
> how-many-changesets-to-become-Committer). Nor is the manual 
> "informative" in the sense of giving tutorials, discussion, or rationale 
> about a normative artifact. It's definitional, like the Bylaws.

Agreed, so far.

> 2. Now turn to normative processes that use the technical 
> infrastructure: filing a bug, producing and shepherding a changeset, 
> ensuring compatibility using CSR, etc. For these topics, there is 
> established behavior that every OpenJDK Participant must follow. It 
> seems to me that this is what the CfV really wanted to document with 
> "tutorial style texts". By all means present the process of filing a bug 
> as a tutorial, but don't pretend it's merely a "non-authoritative 
> suggestion". There is plainly a right way, a norm, an authoritative 
> suggestion when it comes to filing a bug, or formatting a changeset 
> comment, or thinking about the source/binary/behavioral compatibility of 
> a change.

As hinted at the CfV text that you quoted above, the Developer's Guide
is not meant to define normative rules and processes but, rather, to
elaborate upon them when helpful so that new contributors can get up to
speed.  The actual definitions of normative rules and other information
are meant to reside in the hypothetical JEP “outside the scope of this
project” that “will be developed as part of a separate effort in
parallel.”  That’s essentially a JEP for the JDK development process
intended to be a sibling to JEP 3, the JDK release process.

My expectation, which I discussed with Jesper when he was thinking of
proposing the Guide Project, is that as the Guide contributors create or
incorporate material for which a normative definition is needed, but does
not yet exist, then that will drive the draft of the development-process
JEP.  New contributors will find the Guide a good way to get started.
Experienced contributors can simply refer to the JEP for the short-form
definitions of normative information.

> 3. Now turn to informative content that every OpenJDK Participant is 
> free to ignore without consequence. I think you're saying that this 
> could include non-authoritative suggestions about the formatting of Java 
> source code in an OpenJDK repository. However, I agree with Mark: any 
> document connected with Oracle that concerns Java code formatting will 
> be taken as normative, authoritative rules by a broad swathe of the 
> worldwide Java developer community. I can tell you 20 ways that people 
> will interpret your content as "Oracle's Official Java Coding 
> Guidelines". (Example: "In this article on $DEVELOPER_NEWS_SITE, we 
> examine Oracle's new coding guide, and see how it compares with guides 
> from Google and Alibaba!" -- the writer is incentivized to get views, 
> not to make Magnus happy with how the guidelines are characterized.)

This is exactly my primary concern.  No matter how we label a code-style
document, it will be considered authoritative by many people well beyond
the OpenJDK Community.  We therefore must do a good job of it.  Doing no
job would be better than doing a bad job.

We serve the Java ecosystem.  Like it or not, the eyes of the world are
upon us.

- Mark