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

[Doug Lea]

This seems entirely sensible to me.
I don't offhand recall the process for approving such proposals,
but if we are voting: +1

-Doug


On 02/21/2018 02:27 AM, David Holmes wrote:
> 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
> 
>