Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot

[David Holmes]

On 1/03/2018 4:06 AM, joe darcy wrote:
> Hello,
> 
> On 2/28/2018 7:45 AM, mark.reinhold at oracle.com wrote:
>> 2018/2/27 15:13:29 -0800,joe.darcy at oracle.com:
>>> Hi David,
>>>
>>> In terms of how the documentation of this should be structured, I think
>>> the details of the HotSpot policy should be written up in a
>>> HotSpot-specific area, such as HotSpot wiki
>>> (https://wiki.openjdk.java.net/display/HotSpot/Main). Afterward, the CSR
>>> documentation can be amended to refer to this policy by reference.
>> I think it would be best for the entire CSR process to be defined in one
>> place rather than spread out over various wiki pages that may be, to a
>> new reader, of uncertain authority.
>>
> 
> The most relevant part of the existing CSR document is one of the FAQ items:
> 
>> Q: What sort of changes require CSR review?
>> A: Any change to a JDK interface meant to be used outside of the JDK 
>> itself requires CSR review. In this context "interface" isn't limited 
>> to the Java programing language definition of an interface, but 
>> encompasses the broader concept of a protocol between the JDK and 
>> users of the JDK. Examples of interfaces by this definition include:
>>
>>   * Changes to public exported APIs in java.* and javax.* packages.
>>   * Changes to public and exported APIs in jdk.*packages.
>>   * New language updates to the Java Programming Language
>>   * New structures in the Java Virtual Machine Specification
>>   * Adding or removing a command in $JDK/bin
>>   * Adding, removing, or changing a command line option
>>   * Using or defining an environment variable
>>   * Using or defining a new file format or wire format
>>   * Changing or defining a new system or security property
>>
> 
> In the context of this CSR FAQ item, I think a reasonable 
> update/clarification would be "Interfaces that are experimental or for 
> diagnostic purposes do not need to go through CSR, but the CSR may be 
> consulted for feedback if desired."  (Related update: incubating APIs 
> should go through CSR.)

I think the above part of the FAQ certainly needs to be updated to make 
the distinction we want between product flags (under CSR) and 
non-product flags [including experimental and diagnostic] (not under 
CSR). The more detailed description of the different kinds of flags, 
their lifecycle process and their CSR status - can go on the hotspot wiki.

To be honest I'd prefer to see the details of the CSR 
requirements/applicability spelt out directly in a process document 
rather than as a FAQ item.

David

> I don't think adding a detailed explanation of the six kinds of flags 
> HotSpot currently defines is a good fit in this document.
> 
> -Joe