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

[joe darcy]

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 don't think adding a detailed explanation of the six kinds of flags 
HotSpot currently defines is a good fit in this document.

-Joe