RFR: Updated section on Code Conventions.

[Jesper Wilhelmsson]

I'll make an attempt at summarizing this discussion so far. There are a few issues that seems to be key to decide where a Style Guide can be located, all of them have pros and cons. The list below is not sorted in any way.

1) Version control
   + Any git/mercurial based solution will work here.
   + Even the OpenJDK wiki that was briefly mentioned have adequate change history.
   - A traditional JBS-based JEP will not work.

2) Small, controlled, set of editors
   + A JEP has a natural small set of authors and editors. Even though it's not explicitly written anywhere that people shouldn't edit random JEPs I haven't seen a lot of random edits on other people's JEPs. It would be good to explicitly clarify that JEPs are not to be edited without talking to the Author first, but that's a general JEP thing and is unrelated to this discussion.
   + A separate project or a Group maintaining its own document would also achieve this.
   + Having a separate document in the Developers' Guide project can also achieve this. We already have examples of different files/areas in the same Project and source tree (in the JDK) with different rules for reviews and different sets of authors. The same holds true for having the Style Guide reside in the JDK repository.
   - A wiki page will not satisfy this.

3) Make it obvious that this is an OpenJDK style guide
   + A JEP will provide enough "frame" around the Style Guide to make it obvious that this is intended for OpenJDK.
   + Any solution where the Style Guide is a separate document can achieve this as you can decorate the guide with any desired wording to make it scream OpenJDK in the same way as a JEP would do.
   + Having the Style Guide as an inlined chapter in the Developers' Guide will achieve this, but it has never been my intention to inline the Style Guide within the Developers' Guide even if that guide may be merged into a single page. I don't think this is a good idea and it won't happen.

4) Make sure changes are broadly reviewed
   - No solution discussed so far will achieve this.  Changes in JEPs are usually not reviewed at all.  Changes in a separate repository (special JEP, Developers' Guide, or other repo) are only reviewed by those who follow that repo. The only way to get a wide audience to look at changes would be to send them to jdk-dev, and this would have to be explicitly stated in some change guide for the Style Guide regardless of where it is published. The exception may be if the Style Guide is located in the JDK source repo, then it could be standard procedure to send changes for review on jdk-dev.


It seems to me that there are several options that fulfills three out of four requirements, and in order to meet the last one a separate paragraph with a set of rules for updates would be required regardless of where and how the Style Guide is published. Such a paragraph could easily define who is allowed to edit and how reviews should happen.

I personally don't have a strong opinion on where to place the Style Guide other than what I've said before; If it's supposed to be rules rather than guidelines then a JEP is a good place, if these are guidelines I would personally not vote for a JEP. Several experienced voices has expressed what I interpret as "these are rules regardless of what we call them", and I have no evidence to support any other opinion.

As a side note I just want to point out that we are currently three Reviewers in the Developers' Guide Project, none who is likely to accept changes to the Style Guide without following the proper protocol. So I can pretty much guarantee that no random updates will happen if the Style Guide would be placed there. There is some more work to do before the same claim can be made for a JEP.

/Jesper


> On 2 Jul 2020, at 14:06, Lance Andersen <LANCE.ANDERSEN at ORACLE.COM> wrote:
>> On Jul 1, 2020, at 11:54 PM, Stuart Marks <stuart.marks at oracle.com <mailto:stuart.marks at oracle.com>> wrote:
>> On 7/1/20 1:44 AM, Magnus Ihse Bursie wrote:
>>>> A style guide is fundamentally different. To be useful, it must be authoritative -- as mentioned above -- and it also must be highly cohesive. It needs to have a uniform editorial voice that is adhered to consistently throughout the document. For example, it might take a prescriptive vs. a descriptive stance, or it might choose a vocabulary for recommendations of varying strength ("can", "should", "must", etc.) and use that throughout the document. As such, a style guide is not at all amenable to a "crowdsourcing" approach and must be edited by a handful of individuals. Since the editorial approach for the style guide material is so different from that of the Developer's Guide, it follows that the style guide should be a different document.
>>>> 
>>>> Personally I'm agnostic to the exact process for delivering a style guide. If Mark thinks a JEP is required, then maybe that's the best way forward. But I could imagine other paths forward that wouldn't use a JEP.
>>>> 
>>>> I would strongly recommend against making the style guide itself be a JEP. Today, editing a JEP with more than a page or two of text is already unwieldy. It's easy to introduce errors inadvertently, and history tracking is virtually nonexistent.
>>> Are you suggesting that we should create a sibling project to the Developer's Guide for the style guide(s), with different rules for engagement?
>> 
>> I'm mainly suggesting that the Style Guide not be a chapter plopped into the middle of the Developer's Guide. They seem like fundamentally different documents and so should be treated differently.
>> 
> 
> +1
> 
>> That said, where would the Style Guide reside? It could be in a separate OpenJDK Project, though that seems like kind of high overhead for a single document. A Project would have separate Reviewers/Committers/Authors, which also seems like high overhead, but maybe something like that is necessary. Or maybe it could be a Group. For example, recently formed groups like the CSR group and the Vulnerability group have their own, special rules of engagement.
>> 
>> Or, the Style Guide could be hosted in the Developer's Guide *Project* but still be a different document, with different norms around who is responsible for modifying and reviewing changes.
> 
> How about we keep this simple to start and keep this as an additional document in the Developer Guide Project.  If we find the need to place it in its own project later, then we can.
> 
> I think it is more important to move forward with the updates to the style guide now that we have some momentum behind doing so.
> 
>> If the Style Guide has a single editor, or a small editorial board who are responsible for updating it, and everybody understands this, that might work just fine.
> 
> +1
> 
>> This works for code. For example, I'm a libraries guy, so I don't go mucking around in Hotspot without talking to Hotspot folks about it first.
>> 
> +1
> 
> 
>> s'marks
> 
> 
> Best
> Lance
> ------------------
> 
> <oracle_sig_logo.gif>
> 
> 
> Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
> Oracle Java Engineering
> 1 Network Drive
> Burlington, MA 01803
> Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>