From david.holmes at oracle.com Wed Feb 21 07:27:27 2018 From: david.holmes at oracle.com (David Holmes) Date: Wed, 21 Feb 2018 17:27:27 +1000 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot Message-ID: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> 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 From Alan.Bateman at oracle.com Wed Feb 21 09:20:13 2018 From: Alan.Bateman at oracle.com (Alan Bateman) Date: Wed, 21 Feb 2018 09:20:13 +0000 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> Message-ID: <6a80cc6a-a274-622f-10e5-39f9e61cda8c@oracle.com> On 21/02/2018 07:27, David Holmes wrote: > : > > 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. The proposal to track additions/changes to product and manageable options looks reasonable. It's more than I expected to be honest as we've always had undocumented product options used in deployments. Also the proposal to not track develop or notproduct options looks reasonable too. I just skimmed the G1 chapter of the GC tuning guide where it documents -XX:+UnlockExperimentalVMOptions and several experimental G1 options. Given "Experimental" in the unlock option name then I think the proposal to not CSR experimental options is okay. There may be a few places where docs need to make it very clear that experimental options may obsolete or expire without first being deprecated. I'm less sure about diagnostics options.? I just skimmed the documentation for the `java` launcher where it lists many -XX options. I don't think this is the right documentation page for these options but that's a different discussion. One of the options listed is -XX:+LogCompilation which of course needs -XX:+UnlockDiagnosticVMOptions to unlock. This leads me to options such as LogFile and LogVMOutput, both legacy now, but I'll bet there are many existing deployments using these options. So while I think your proposal is okay, I think we will need to be careful a small number of existing and legacy diagnostic options, some of these may need a CSR and/or release note to create awareness of a change. -Alan From dl at cs.oswego.edu Wed Feb 21 11:50:26 2018 From: dl at cs.oswego.edu (Doug Lea) Date: Wed, 21 Feb 2018 06:50:26 -0500 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> Message-ID: 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 > > From joe.darcy at oracle.com Fri Feb 23 23:53:39 2018 From: joe.darcy at oracle.com (Joseph D. Darcy) Date: Fri, 23 Feb 2018 15:53:39 -0800 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> Message-ID: <5A90A983.4010900@oracle.com> Hello, Catching up on email, I think the general thrust of the proposal is reasonable, but I have a few questions and comments. First, what is the full space of kinds of builds, product XOR debug? What syntactic conventions, if any, distinguish all these kinds of flags? Are product and manageable "-X" and all the others "-XX"? (I've previously suggested in jest that a "-XXX" prefix be used for less wholesome options.) If so, rather than reading of the general CSR guidelines and concluding "[the guidelines] places all [HotSpot] -XX options into the same CSR basket," an alternative observation might be the HotSpot naming conventions choose to put multiple distinct kinds of options into the same small namespace. Do options commonly move between categories as part of their lifecycle (e.g. experimental -> product, etc.)? Thanks, -Joe On 2/20/2018 11:27 PM, 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 > ------ From david.holmes at oracle.com Sat Feb 24 06:08:27 2018 From: david.holmes at oracle.com (David Holmes) Date: Sat, 24 Feb 2018 16:08:27 +1000 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <5A90A983.4010900@oracle.com> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> <5A90A983.4010900@oracle.com> Message-ID: <536eb7a0-c02b-cc42-2e3f-e50510a4cb1d@oracle.com> Hi Joe, On 24/02/2018 9:53 AM, Joseph D. Darcy wrote: > Hello, > > Catching up on email, I think the general thrust of the proposal is > reasonable, but I have a few questions and comments. > > First, what is the full space of kinds of builds, product XOR debug? First distinction is product vs development Development can then be: fastdebug (aka debug), slowdebug, or optimized (the exact definition of which I can't recall but this is a build variation we are removing anyway). > What syntactic conventions, if any, distinguish all these kinds of > flags? Are product and manageable "-X" and all the others "-XX"? (I've > previously suggested in jest that a "-XXX" prefix be used for less > wholesome options.) There are no syntactic distinctions - these are all -XX flags, regardless of whether product or development, experimental etc. That is the long standing convention for hotspot specific flags. > If so, rather than reading of the general CSR guidelines and concluding > "[the guidelines] places all [HotSpot] -XX options into the same CSR > basket," an alternative observation might be the HotSpot naming > conventions choose to put multiple distinct kinds of options into the > same small namespace. We only have one namespace for hotspot options. > Do options commonly move between categories as > part of their lifecycle (e.g. experimental -> product, etc.)? Not commonly. An experimental flag may become product if the experimental feature is adopted - that would of course have a CSR request at that point. Sometimes a product flag can be reclassified as develop, or vice-versa - both of which would again require CSR requests as they involve a product flag. Most commonly flags stay in their initial category. Thanks, David > Thanks, > > -Joe > > On 2/20/2018 11:27 PM, 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 >> ------ > From joe.darcy at oracle.com Tue Feb 27 01:11:26 2018 From: joe.darcy at oracle.com (Joseph D. Darcy) Date: Mon, 26 Feb 2018 17:11:26 -0800 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <536eb7a0-c02b-cc42-2e3f-e50510a4cb1d@oracle.com> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> <5A90A983.4010900@oracle.com> <536eb7a0-c02b-cc42-2e3f-e50510a4cb1d@oracle.com> Message-ID: <5A94B03E.5050406@oracle.com> Hi David, On 2/23/2018 10:08 PM, David Holmes wrote: > Hi Joe, > > On 24/02/2018 9:53 AM, Joseph D. Darcy wrote: >> Hello, >> >> Catching up on email, I think the general thrust of the proposal is >> reasonable, but I have a few questions and comments. >> >> First, what is the full space of kinds of builds, product XOR debug? > > First distinction is product vs development > > Development can then be: fastdebug (aka debug), slowdebug, or > optimized (the exact definition of which I can't recall but this is a > build variation we are removing anyway). Okay. > >> What syntactic conventions, if any, distinguish all these kinds of >> flags? Are product and manageable "-X" and all the others "-XX"? >> (I've previously suggested in jest that a "-XXX" prefix be used for >> less wholesome options.) > > There are no syntactic distinctions - these are all -XX flags, > regardless of whether product or development, experimental etc. That > is the long standing convention for hotspot specific flags. > >> If so, rather than reading of the general CSR guidelines and >> concluding "[the guidelines] places all [HotSpot] -XX options into >> the same CSR basket," an alternative observation might be the HotSpot >> naming conventions choose to put multiple distinct kinds of options >> into the same small namespace. > > We only have one namespace for hotspot options. > >> Do options commonly move between categories as part of their >> lifecycle (e.g. experimental -> product, etc.)? > > Not commonly. An experimental flag may become product if the > experimental feature is adopted - that would of course have a CSR > request at that point. Sometimes a product flag can be reclassified as > develop, or vice-versa - both of which would again require CSR > requests as they involve a product flag. Most commonly flags stay in > their initial category. > Here is a possible alternative long-term arrangement for your consideration: the debug-ness, experimental-ness, etc. is encoded into the name of the option, instead of -XX:FooBarBaz, something like -XX:ExperFooBarBaz, or -XX:DebugFooBarBaz, etc. In the mean time, I think the proposal put forward is acceptable. Cheers, -Joe From david.holmes at oracle.com Tue Feb 27 01:48:58 2018 From: david.holmes at oracle.com (David Holmes) Date: Tue, 27 Feb 2018 11:48:58 +1000 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <5A94B03E.5050406@oracle.com> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> <5A90A983.4010900@oracle.com> <536eb7a0-c02b-cc42-2e3f-e50510a4cb1d@oracle.com> <5A94B03E.5050406@oracle.com> Message-ID: Hi Joe, On 27/02/2018 11:11 AM, Joseph D. Darcy wrote: > Hi David, > > On 2/23/2018 10:08 PM, David Holmes wrote: >> Hi Joe, >> >> On 24/02/2018 9:53 AM, Joseph D. Darcy wrote: >>> Hello, >>> >>> Catching up on email, I think the general thrust of the proposal is >>> reasonable, but I have a few questions and comments. >>> >>> First, what is the full space of kinds of builds, product XOR debug? >> >> First distinction is product vs development >> >> Development can then be: fastdebug (aka debug), slowdebug, or >> optimized (the exact definition of which I can't recall but this is a >> build variation we are removing anyway). > > Okay. > >> >>> What syntactic conventions, if any, distinguish all these kinds of >>> flags? Are product and manageable "-X" and all the others "-XX"? >>> (I've previously suggested in jest that a "-XXX" prefix be used for >>> less wholesome options.) >> >> There are no syntactic distinctions - these are all -XX flags, >> regardless of whether product or development, experimental etc. That >> is the long standing convention for hotspot specific flags. >> >>> If so, rather than reading of the general CSR guidelines and >>> concluding "[the guidelines] places all [HotSpot] -XX options into >>> the same CSR basket," an alternative observation might be the HotSpot >>> naming conventions choose to put multiple distinct kinds of options >>> into the same small namespace. >> >> We only have one namespace for hotspot options. >> >>> Do options commonly move between categories as part of their >>> lifecycle (e.g. experimental -> product, etc.)? >> >> Not commonly. An experimental flag may become product if the >> experimental feature is adopted - that would of course have a CSR >> request at that point. Sometimes a product flag can be reclassified as >> develop, or vice-versa - both of which would again require CSR >> requests as they involve a product flag. Most commonly flags stay in >> their initial category. >> > > Here is a possible alternative long-term arrangement for your > consideration: the debug-ness, experimental-ness, etc. is encoded into > the name of the option, instead of -XX:FooBarBaz, something like > -XX:ExperFooBarBaz, or -XX:DebugFooBarBaz, etc. Certainly if we were starting from scratch I'd be looking at a much more versatile format for flags, including effective namespaces. As to whether we're likely to invest effort in this area ... for now the main goal is to bring the number of flags under control. > In the mean time, I think the proposal put forward is acceptable. Thanks! So do we have a process here? Wait a week for any objections, then write this up on the CSR wiki somewhere ? Cheers, David ----- > Cheers, > > -Joe From joe.darcy at oracle.com Tue Feb 27 23:13:29 2018 From: joe.darcy at oracle.com (joe darcy) Date: Tue, 27 Feb 2018 15:13:29 -0800 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> <5A90A983.4010900@oracle.com> <536eb7a0-c02b-cc42-2e3f-e50510a4cb1d@oracle.com> <5A94B03E.5050406@oracle.com> Message-ID: <4bca3d26-947b-bd7b-2ffa-ace7c7bf8044@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. What do you think? Thanks, -Joe On 2/26/2018 5:48 PM, David Holmes wrote: > Hi Joe, > > On 27/02/2018 11:11 AM, Joseph D. Darcy wrote: >> Hi David, >> >> On 2/23/2018 10:08 PM, David Holmes wrote: >>> Hi Joe, >>> >>> On 24/02/2018 9:53 AM, Joseph D. Darcy wrote: >>>> Hello, >>>> >>>> Catching up on email, I think the general thrust of the proposal is >>>> reasonable, but I have a few questions and comments. >>>> >>>> First, what is the full space of kinds of builds, product XOR debug? >>> >>> First distinction is product vs development >>> >>> Development can then be: fastdebug (aka debug), slowdebug, or >>> optimized (the exact definition of which I can't recall but this is >>> a build variation we are removing anyway). >> >> Okay. >> >>> >>>> What syntactic conventions, if any, distinguish all these kinds of >>>> flags? Are product and manageable "-X" and all the others "-XX"? >>>> (I've previously suggested in jest that a "-XXX" prefix be used for >>>> less wholesome options.) >>> >>> There are no syntactic distinctions - these are all -XX flags, >>> regardless of whether product or development, experimental etc. That >>> is the long standing convention for hotspot specific flags. >>> >>>> If so, rather than reading of the general CSR guidelines and >>>> concluding "[the guidelines] places all [HotSpot] -XX options into >>>> the same CSR basket," an alternative observation might be the >>>> HotSpot naming conventions choose to put multiple distinct kinds of >>>> options into the same small namespace. >>> >>> We only have one namespace for hotspot options. >>> >>>> Do options commonly move between categories as part of their >>>> lifecycle (e.g. experimental -> product, etc.)? >>> >>> Not commonly. An experimental flag may become product if the >>> experimental feature is adopted - that would of course have a CSR >>> request at that point. Sometimes a product flag can be reclassified >>> as develop, or vice-versa - both of which would again require CSR >>> requests as they involve a product flag. Most commonly flags stay in >>> their initial category. >>> >> >> Here is a possible alternative long-term arrangement for your >> consideration: the debug-ness, experimental-ness, etc. is encoded >> into the name of the option, instead of -XX:FooBarBaz, something like >> -XX:ExperFooBarBaz, or -XX:DebugFooBarBaz, etc. > > Certainly if we were starting from scratch I'd be looking at a much > more versatile format for flags, including effective namespaces. As to > whether we're likely to invest effort in this area ... for now the > main goal is to bring the number of flags under control. > >> In the mean time, I think the proposal put forward is acceptable. > > Thanks! So do we have a process here? Wait a week for any objections, > then write this up on the CSR wiki somewhere ? > > Cheers, > David > ----- > >> Cheers, >> >> -Joe From david.holmes at oracle.com Tue Feb 27 23:50:34 2018 From: david.holmes at oracle.com (David Holmes) Date: Wed, 28 Feb 2018 09:50:34 +1000 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <4bca3d26-947b-bd7b-2ffa-ace7c7bf8044@oracle.com> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> <5A90A983.4010900@oracle.com> <536eb7a0-c02b-cc42-2e3f-e50510a4cb1d@oracle.com> <5A94B03E.5050406@oracle.com> <4bca3d26-947b-bd7b-2ffa-ace7c7bf8044@oracle.com> Message-ID: Hi Joe, On 28/02/2018 9:13 AM, joe darcy wrote: > 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. > > What do you think? That sounds fine. I'll find out how to write to our wiki. Thanks, David > Thanks, > > -Joe > > > On 2/26/2018 5:48 PM, David Holmes wrote: >> Hi Joe, >> >> On 27/02/2018 11:11 AM, Joseph D. Darcy wrote: >>> Hi David, >>> >>> On 2/23/2018 10:08 PM, David Holmes wrote: >>>> Hi Joe, >>>> >>>> On 24/02/2018 9:53 AM, Joseph D. Darcy wrote: >>>>> Hello, >>>>> >>>>> Catching up on email, I think the general thrust of the proposal is >>>>> reasonable, but I have a few questions and comments. >>>>> >>>>> First, what is the full space of kinds of builds, product XOR debug? >>>> >>>> First distinction is product vs development >>>> >>>> Development can then be: fastdebug (aka debug), slowdebug, or >>>> optimized (the exact definition of which I can't recall but this is >>>> a build variation we are removing anyway). >>> >>> Okay. >>> >>>> >>>>> What syntactic conventions, if any, distinguish all these kinds of >>>>> flags? Are product and manageable "-X" and all the others "-XX"? >>>>> (I've previously suggested in jest that a "-XXX" prefix be used for >>>>> less wholesome options.) >>>> >>>> There are no syntactic distinctions - these are all -XX flags, >>>> regardless of whether product or development, experimental etc. That >>>> is the long standing convention for hotspot specific flags. >>>> >>>>> If so, rather than reading of the general CSR guidelines and >>>>> concluding "[the guidelines] places all [HotSpot] -XX options into >>>>> the same CSR basket," an alternative observation might be the >>>>> HotSpot naming conventions choose to put multiple distinct kinds of >>>>> options into the same small namespace. >>>> >>>> We only have one namespace for hotspot options. >>>> >>>>> Do options commonly move between categories as part of their >>>>> lifecycle (e.g. experimental -> product, etc.)? >>>> >>>> Not commonly. An experimental flag may become product if the >>>> experimental feature is adopted - that would of course have a CSR >>>> request at that point. Sometimes a product flag can be reclassified >>>> as develop, or vice-versa - both of which would again require CSR >>>> requests as they involve a product flag. Most commonly flags stay in >>>> their initial category. >>>> >>> >>> Here is a possible alternative long-term arrangement for your >>> consideration: the debug-ness, experimental-ness, etc. is encoded >>> into the name of the option, instead of -XX:FooBarBaz, something like >>> -XX:ExperFooBarBaz, or -XX:DebugFooBarBaz, etc. >> >> Certainly if we were starting from scratch I'd be looking at a much >> more versatile format for flags, including effective namespaces. As to >> whether we're likely to invest effort in this area ... for now the >> main goal is to bring the number of flags under control. >> >>> In the mean time, I think the proposal put forward is acceptable. >> >> Thanks! So do we have a process here? Wait a week for any objections, >> then write this up on the CSR wiki somewhere ? >> >> Cheers, >> David >> ----- >> >>> Cheers, >>> >>> -Joe > From mark.reinhold at oracle.com Wed Feb 28 15:45:26 2018 From: mark.reinhold at oracle.com (mark.reinhold at oracle.com) Date: Wed, 28 Feb 2018 07:45:26 -0800 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <4bca3d26-947b-bd7b-2ffa-ace7c7bf8044@oracle.com> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> <5A90A983.4010900@oracle.com> <536eb7a0-c02b-cc42-2e3f-e50510a4cb1d@oracle.com> <5A94B03E.5050406@oracle.com> <4bca3d26-947b-bd7b-2ffa-ace7c7bf8044@oracle.com> Message-ID: <20180228074526.75990263@eggemoggin.niobe.net> 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. - Mark From joe.darcy at oracle.com Wed Feb 28 18:06:28 2018 From: joe.darcy at oracle.com (joe darcy) Date: Wed, 28 Feb 2018 10:06:28 -0800 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <20180228074526.75990263@eggemoggin.niobe.net> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> <5A90A983.4010900@oracle.com> <536eb7a0-c02b-cc42-2e3f-e50510a4cb1d@oracle.com> <5A94B03E.5050406@oracle.com> <4bca3d26-947b-bd7b-2ffa-ace7c7bf8044@oracle.com> <20180228074526.75990263@eggemoggin.niobe.net> Message-ID: <42a1f643-533f-1a1b-531b-5454deb0ac74@oracle.com> 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 From mark.reinhold at oracle.com Wed Feb 28 18:16:35 2018 From: mark.reinhold at oracle.com (mark.reinhold at oracle.com) Date: Wed, 28 Feb 2018 10:16:35 -0800 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <42a1f643-533f-1a1b-531b-5454deb0ac74@oracle.com> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> <5A90A983.4010900@oracle.com> <536eb7a0-c02b-cc42-2e3f-e50510a4cb1d@oracle.com> <5A94B03E.5050406@oracle.com> <4bca3d26-947b-bd7b-2ffa-ace7c7bf8044@oracle.com> <20180228074526.75990263@eggemoggin.niobe.net> <42a1f643-533f-1a1b-531b-5454deb0ac74@oracle.com> Message-ID: <20180228101635.76529502@eggemoggin.niobe.net> 2018/2/28 10:06:28 -0800, joe.darcy at oracle.com: > 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. If HotSpot's experimental/diagnostic flags are not subject to CSR review then I agree that they can be documented outside of the CSR process itself. - Mark From david.holmes at oracle.com Wed Feb 28 20:51:08 2018 From: david.holmes at oracle.com (David Holmes) Date: Thu, 1 Mar 2018 06:51:08 +1000 Subject: Proposal: Clarifying the CSR rules for dealing with various kinds of -XX flags for hotspot In-Reply-To: <42a1f643-533f-1a1b-531b-5454deb0ac74@oracle.com> References: <8d1ad864-f0a0-430c-5325-c692d39fd5d5@oracle.com> <5A90A983.4010900@oracle.com> <536eb7a0-c02b-cc42-2e3f-e50510a4cb1d@oracle.com> <5A94B03E.5050406@oracle.com> <4bca3d26-947b-bd7b-2ffa-ace7c7bf8044@oracle.com> <20180228074526.75990263@eggemoggin.niobe.net> <42a1f643-533f-1a1b-531b-5454deb0ac74@oracle.com> Message-ID: 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