RFR: Updated section on Code Conventions.

[Alex Buckley]

On 6/27/2020 1:21 AM, Jesper Wilhelmsson wrote:
>> On 27 Jun 2020, at 00:42, Alex Buckley <alex.buckley at oracle.com 
>> <mailto:alex.buckley at oracle.com>> wrote:
>> 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. ...
> 
> There are parts like this in the current guide and there will be more of 
> this kind going forward. The mailing lists recently got a new 
> description [0]. It hasn't been released to the webserver yet, but it's 
> in GitHub.

Yes, I saw mailingLists.md, but it and the other RFRs on guide-dev are 
all bottom-up changes that preserve the oddball structure of the current 
Guide. I'm suggesting top-down changes -- write out a new Table Of 
Contents so as to categorize (1) the normative, uncontroversial content 
about technical infrastructure (e.g., mailing list suffixes); (2) the 
normative, controversial content about development practices where (say) 
different Projects have different views and you need to set expectations 
in general; and (3) informative background material (e.g. timeline of 
feature releases by the JDK Project; history of leadership in the JDK 
6/7u/8u Projects).

> I'm not sure that I have any good examples of "informative content that 
> every OpenJDK Participant is free to ignore without consequence", that 
> would as you exemplifies here be just stories. I'm not even sure how to 
> interpret the word "informative" here since our process JEPs which are 
> clearly meant to be followed strictly are "informative JEPs". 

To clarify: a "Process JEP" is normative. JEP 3: JDK Release Process is 
a Process JEP because it authoritatively describes a protocol which must 
be followed.

An "Informational JEP" is harder to characterize. Despite the name 
suggesting informative status, the reality is that almost all 
Informational JEPs are normative policy documents:

- JEP 11: Incubator Modules
- JEP 12: Preview Language and VM Features
- JEP 182: Policy for Retiring javac -source and -target Options
- JEP 293: Guidelines for JDK Command-Line Tool Options
- JEP draft: javadoc tags to distinguish API, implementation, 
specification, and notes
- JEP draft: Disable experimental features by default
- JEP draft: Guidelines for documenting system properties
- JEP draft: Keyword Management for the Java Language

(A document can be normative even if the penalty for non-conformance is 
softer than the hard-edged JLS penalty of "A compile-time error occurs 
...". For example, the penalty for not following the guidelines for 
documenting system properties might be more time spent on getting your 
changeset accepted, as you seek to convince Reviewers that your system 
properties really are special and you really do know what you're doing. 
The only Informational JEP which is strictly informative is JEP 188: 
Java Memory Model Update.)

I'm not sure if Mark if saying this exactly, but I can see the 
Informational-means-normative angle serving as a feature, not a bug. An 
Informational JEP "Java Style Guide for OpenJDK Projects" which is 
normative for OpenJDK Projects will be taken as normative for ordinary 
Java programs around the world, but the JEP "wrapper" is a great 
mechanism for stopping outright misrepresentation and confusion.

Alex