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

[David Holmes]

Dear CSR Group Members,

On behalf of the Hotspot team within Oracle, I would like to submit this 
proposal regarding the CSR process for dealing with various -XX Hotspot 
flags.

If this is acceptable then we would like to see this clearly documented 
on the OpenJDK site in a suitable location (and referenced from both 
Hotspot wiki and CSR wiki).

Thank you.
David
------

Summary:
=======

The Hotspot team would like to exempt the addition and removal of 
developer-oriented command-line flags from the need for a CSR request, 
and to streamline the removal process for other flags.

Background:
==========

Hotspot defines 6 kinds of command-line flags:

- product

These are the primary flags we intend end-users to apply for tuning, 
feature selection etc. These are settable via the command-line in 
product builds.

- manageable

These are a special kind of product flag that can be dynamically set via 
the JDK management interface.

- develop

These are flags intended for use by Hotspot developers for debugging and 
testing purposes. These are settable only in non-product builds, and 
have a constant value in product builds.

- not_product

A more constrained development flag that has no presence at all in a 
product build.

- experimental

These flags are in support of features that are not part of the 
officially supported product, but are available in the product for 
experimenting with. They must be explicitly unlocked to be used. They 
are expected to be temporary in nature, and potentially replaced by a 
product flag in a later release if the feature remains. Experimental 
features can be dropped with no notice.

- diagnostic

Diagnostic flags are not meant for VM tuning or for product modes. They
are to be used for VM quality assurance or field diagnosis of VM bugs.
They are hidden so that users will not be encouraged to try them as if
they were product flags. However, they are available in the product
version of the VM so they can be enabled under instruction
to collect diagnostic information about VM problems.


The Hotspot team have a defined (up to) three step deprecation process 
for removing flags:

1. Deprecate: accept the flag, act on it, but warn it is deprecated and 
may be removed in the future.

2. Obsolete: accept the flag but ignore it other than to issue a warning 
it is obsolete and may be removed in the future. This allows code 
associated with the flag to be removed from the codebase.

3. Expired: use of the flag causes an "unknown VM option" error and the 
VM refuses to start.

The full three step process is used for "product" and "manageable" 
flags. For the other flags we can start at step 2 and "obsolete" the 
flag in the current release.

The CSR Process:
===============

 From the Developers Guide [1] we have the definition of "Official" and 
"Unofficial" interfaces, in which it describes as official interfaces " 
... and the names of the options taken by those commands". Which 
indicates the Hotspot -XX options are all to be considered part of an 
"Official interface" (which is different to how they were considered 
under the old CCC).

The CSR FAQ also has:

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:
     ...
     Adding, removing, or changing a command line option

so again this places all -XX options into the same CSR basket.

Proposed Changes:
=================

We propose that only "product" and "manageable" flags should be 
considered part of the "official interface" and subject to the full CSR 
process.

For the other flags, given their nature as part of the "unofficial 
interface", we feel the CSR process is not needed and the code review 
process gives sufficient visibility to the change.

Separately, though related, we will also look into how to document these 
flags in a manner suitable for developers.

We further wish to clarify that for the "product" and "manageable" 
flags, the CSR request made when the flag is initially deprecated, 
serves to cover the entire removal process. That is, we do not need to 
submit further CSR requests when the flag is obsoleted, and then expired.


[1] 
http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.777.html#kinds_of_interfaces