From joe.darcy at oracle.com Thu Apr 6 17:38:25 2017 From: joe.darcy at oracle.com (joe darcy) Date: Thu, 6 Apr 2017 10:38:25 -0700 Subject: Welcome to CSR discuss, conversations on reviewing compatibility and specifications Message-ID: <26cff6c8-6847-2202-120c-e3df46250188@oracle.com> Hello and welcome to csr-discuss, the discussion alias for the compatibility and specification review OpenJDK group. I'd like to work toward getting CSR reviews operational for JDK 10 changes within the next few weeks in anticipation of the JDK 10 lead asking the CSR to review changes in JDK 10. [1] For that review initiation to occur, several items need to happen including: * Configuration changes to the JDK Bug System, JBS (https://bugs.openjdk.java.net), to support a CSR issue type. Inside Oracle, we are working through feedback on earlier iterations of the issue type. * More fundamentally, documentation and discussion about what role the CSR process plays in JDK development. The predecessor ccc process has historically played a number of roles including ensuring high-quality specifications, providing feedback to API developers, and creating an archive of changes as they occur. I expect those broad roles to continue under CSR. * Writing documentation for users of CSR, covering both the conceptual rationale for CSR review as well as the current details of the tooling in JBS. The documentation set may include an update of "OpenJDK Developers' Guide, Version 0.777" [2], which contains a detailed discussion of compatibility concerns. On the logistics of accomplishing the above, I'd like to use the the wiki page for the CSR group https://wiki.openjdk.java.net/display/csr/Main to host the documentation. For using the new issue type, I think it would be helpful to import a number of the ccc requests approved in JDK 9 as CSR issues in JBS in a separate "CCC" project. I'll be screening my JDK 9 ccc requests for this purpose, several dozen in total, and invite other CSR members who have filed ccc requests for JDK 9 to do the same. These imported requests will show the range of some of the kinds of changes the CSR will review, API changes, language updates, command-line flags, etc., and provide exemplars of requests for new users. I think seeing a concrete range of kinds of changes in CSR requests will help foster a better informed discussion than just talking about CSR requests in the abstract. I'll be working on the documentation and will send portions out for review as they become sufficiently mature and will keep the group apprised on when the ccc requests in JBS will be available for viewing. Comments? Thanks, -Joe [1] http://mail.openjdk.java.net/pipermail/gb-discuss/2017-January/000320.html [2] http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.777.html From philip.race at oracle.com Fri Apr 7 16:21:13 2017 From: philip.race at oracle.com (Philip Race) Date: Fri, 07 Apr 2017 09:21:13 -0700 Subject: Welcome to CSR discuss, conversations on reviewing compatibility and specifications In-Reply-To: <26cff6c8-6847-2202-120c-e3df46250188@oracle.com> References: <26cff6c8-6847-2202-120c-e3df46250188@oracle.com> Message-ID: <58E7BC79.6040805@oracle.com> >On the logistics of accomplishing the above, I'd like to use the the wiki page for the CSR group > https://wiki.openjdk.java.net/display/csr/Main That is fine but we also should populate the group page with some information. I know that it can't be edited from outside but it looks pretty empty compared to most. > I think it would be helpful to import a number of the ccc requests approved in JDK 9 as CSR issues in JBS in a separate "CCC" project. ... > and invite other CSR members who have filed ccc requests for JDK 9 to do the same. I will be happy to do so once they are in JBS. -phil. On 4/6/17, 10:38 AM, joe darcy wrote: > Hello and welcome to csr-discuss, the discussion alias for the > compatibility and specification review OpenJDK group. > > I'd like to work toward getting CSR reviews operational for JDK 10 > changes within the next few weeks in anticipation of the JDK 10 lead > asking the CSR to review changes in JDK 10. [1] > > For that review initiation to occur, several items need to happen > including: > > * Configuration changes to the JDK Bug System, JBS > (https://bugs.openjdk.java.net), to support a CSR issue type. Inside > Oracle, we are working through feedback on earlier iterations of the > issue type. > > * More fundamentally, documentation and discussion about what role the > CSR process plays in JDK development. The predecessor ccc process has > historically played a number of roles including ensuring high-quality > specifications, providing feedback to API developers, and creating an > archive of changes as they occur. I expect those broad roles to > continue under CSR. > > * Writing documentation for users of CSR, covering both the conceptual > rationale for CSR review as well as the current details of the tooling > in JBS. The documentation set may include an update of "OpenJDK > Developers' Guide, Version 0.777" [2], which contains a detailed > discussion of compatibility concerns. > > On the logistics of accomplishing the above, I'd like to use the the > wiki page for the CSR group > > https://wiki.openjdk.java.net/display/csr/Main > > to host the documentation. For using the new issue type, I think it > would be helpful to import a number of the ccc requests approved in > JDK 9 as CSR issues in JBS in a separate "CCC" project. I'll be > screening my JDK 9 ccc requests for this purpose, several dozen in > total, and invite other CSR members who have filed ccc requests for > JDK 9 to do the same. These imported requests will show the range of > some of the kinds of changes the CSR will review, API changes, > language updates, command-line flags, etc., and provide exemplars of > requests for new users. I think seeing a concrete range of kinds of > changes in CSR requests will help foster a better informed discussion > than just talking about CSR requests in the abstract. > > I'll be working on the documentation and will send portions out for > review as they become sufficiently mature and will keep the group > apprised on when the ccc requests in JBS will be available for viewing. > > Comments? > > Thanks, > > -Joe > > [1] > http://mail.openjdk.java.net/pipermail/gb-discuss/2017-January/000320.html > > [2] > http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.777.html > From joe.darcy at oracle.com Fri Apr 7 20:24:52 2017 From: joe.darcy at oracle.com (joe darcy) Date: Fri, 7 Apr 2017 13:24:52 -0700 Subject: Welcome to CSR discuss, conversations on reviewing compatibility and specifications In-Reply-To: <58E7BC79.6040805@oracle.com> References: <26cff6c8-6847-2202-120c-e3df46250188@oracle.com> <58E7BC79.6040805@oracle.com> Message-ID: Hi Phil, On 4/7/2017 9:21 AM, Philip Race wrote: > > >On the logistics of accomplishing the above, I'd like to use the the > wiki page for the CSR group > > > https://wiki.openjdk.java.net/display/csr/Main > > That is fine but we also should populate the group page with some > information. > I know that it can't be edited from outside but it looks pretty empty > compared to most. Agreed; I'll update the page to state something like "Look at the wiki instead of here." > > > I think it would be helpful to import a number of the ccc requests > approved in JDK 9 as CSR issues in JBS in a separate "CCC" project. > ... > > and invite other CSR members who have filed ccc requests for JDK 9 > to do the same. > > I will be happy to do so once they are in JBS. Thanks; it will be good to see requests from multiple people. Cheers, -Joe From joe.darcy at oracle.com Sat Apr 8 02:56:10 2017 From: joe.darcy at oracle.com (joe darcy) Date: Fri, 7 Apr 2017 19:56:10 -0700 Subject: Initial CSR FAQ items Message-ID: <0bb7f08f-f047-f23b-01da-bdf32cfb59c6@oracle.com> Hello, Please review and comment on the the starter population of FAQ items below. These FAQ items generally do not deal with the logistics of using the CSR issue type; such items will be written after there is a public prototype of the CSR issue type. Eventually, all FAQ items will be nestled in the context of other CSR documentation. Other anticipated FAQ items to be covered? Thanks, -Joe Q: What is the CSR? A: The CSR is a review body for changes being made in JDK releases. The letters "CSR" stand for "compatibility and specification review"; therefore the CSR focuses on reviewing specifications (as opposed to implementations) with an emphasis on long-term compatibility impact. Besides compatibly review, review of a specification includes but is not limited to abiding by naming conventions, clear description of semantics, appropriate use of language features, and so on. The compatibility review is not strictly limited to specifications; some implementation-only changes with compatibility impact merit CSR review as well. Q: Who are the CSR group members? A: The current membership of the CSR group is listed in the OpenJDK census (http://openjdk.java.net/census#csr). The members of the CSR are experienced in JDK development and have deep knowledge of one or more areas of the platform. Q: What kinds of compatibly does the CSR look after? A: The CSR looks after source, binary, and behavioral compatibility. Binary compatibility is the ability of existing binaries to link. Source compatibility concerns whether or not existing code still compiles and if it still compiles, if it compiles into an equivalent binary. Behavioral compatibility involves operational equivalence; with "the same" inputs, does a program behave "the same way" before and after a change. More detailed and nuanced discussion of these compatibility concerns can be found in "OpenJDK Developers' Guide, Version 0.777" (http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.777.html#behavioral_compatibility). (Note: the material in this guide should eventually be updated and incorporated more directly into the CSR documents.) 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 Q: Timing wise, when do I need to file a CSR request? A: A CSR request needs to be filed and approved *before* the corresponding change is pushed to a JDK release line of development. In exceptional circumstances, the need for a CSR review may be recognized only after a push has already occurred. In such cases, a retroactive CSR review can be conducted. The results of such a retroactive review may require updates to the change, up to and including complete removal of the change. Q: How long does a CSR review take? A: The scope of CSR requests varies over several orders of magnitudes. Large requests should expected to take longer to review than small ones. The CSR strives to complete its initial review of a proposal within one week. If the CSR has feedback, the time its takes for an engineer working on the proposal to respond to and act upon the feedback may take more than one week after the proposal was submitted to the CSR. Q: I have a deadline coming up. Can I ask for the CSR for an expedited review? A: Engineers are free to request an expedited review from the CSR. Conversely, the CSR is free to decline such requests. Q: If my change needs a CSR review and a code review, which should I do first? A: To take a common case of a Java API change, there is some overlap between the factors considered in a general code review and the factors considered by the CSR when reviewing the specification and compatibility impact. (CSR members often participate in code reviews in addition to their reviews in CSR roles.) An engineer may choose to run the CSR process and code review in parallel, but feedback from either channel may be received which requires updates to the proposal in the other channel. If an engineer chooses to sequence code review and CSR review, to minimize latency the process expected to provide more feedback should be run first. Q: Who should be a reviewer on a CSR proposal? A: One or more engineers with expertise in the areas impacted by the proposed change should review the CSR request and be listed as a reviewer before the proposal is reviewed by the CSR membership. (These engineers may or may not be Reviewers (http://openjdk.java.net/bylaws#reviewer) on the corresponding JDK project.) It is appropriate to ask a CSR member to review a request in a area where he or she has expertise, but it is not necessary for a CSR member to review a request before the CSR body considers it. To encourage wider reviews, it is preferable if the CSR chair is not the only reviewer of a CSR request. The CSR may request a proposal be reviewed by additional engineers before further considering the request. Q: Should people providing feedback via CSR be listed a reviewers when a changeset is pushed? A: If CSR reviews prompts modifications to what gets pushed, it is reasonable to include as the CSR members providing the feedback among the reviewers of the changeset. Q: If I don't agree with the outcome of CSR review, what recourse do I have? A: The CSR review strives to reach a consensus on the appropriate engineering outcome for a proposal, including what modifications to a proposal are necessary to bring the proposal in line with overall JDK goals. If such a consensus is not reached, since the CSR process is used at the request of the Lead for a JDK release project (http://mail.openjdk.java.net/pipermail/gb-discuss/2017-January/000320.html), appeals about the CSR's determination of a request for a particular JDK release can be made to the Lead of the release in question. Q: If the text of the javadoc of a public exported API is changing, is a CSR request needed? A: A CSR request is required if the *specification* of a public exported API. Not all javadoc updates are specification changes. For example, typo fixes and rephrasings that do not alter the semantics of the API in question do *not* require CSR review. Q: What is the relationship between a CSR and a JEP? A: A JEP (JDK Enhancement-Proposal, http://openjdk.java.net/jeps/0) initially describes a project to update some aspect of the JDK. The exact details of the updates are usually not yet known when the JEP begins. As the JEP matures, the updates to the JDK associated with the JEP are pushed under on more more changesets. Each changesets that involves a specification change (or sufficiently large compatibility impact) would also require CSR review. From dl at cs.oswego.edu Sun Apr 9 14:18:21 2017 From: dl at cs.oswego.edu (Doug Lea) Date: Sun, 9 Apr 2017 10:18:21 -0400 Subject: Initial CSR FAQ items In-Reply-To: <0bb7f08f-f047-f23b-01da-bdf32cfb59c6@oracle.com> References: <0bb7f08f-f047-f23b-01da-bdf32cfb59c6@oracle.com> Message-ID: On 04/07/2017 10:56 PM, joe darcy wrote: > Hello, > > Please review and comment on the the starter population of FAQ items > below. These FAQ items generally do not deal with the logistics of using > the CSR issue type; such items will be written after there is a public > prototype of the CSR issue type. The only other questions I can think of are logistics related. So, so far, it looks good to me! Thanks for taking this on. -Doug From joe.darcy at oracle.com Tue Apr 11 18:24:16 2017 From: joe.darcy at oracle.com (joe darcy) Date: Tue, 11 Apr 2017 11:24:16 -0700 Subject: Initial CSR FAQ items In-Reply-To: References: <0bb7f08f-f047-f23b-01da-bdf32cfb59c6@oracle.com> Message-ID: <8613af88-c44c-e5f5-01bf-8b954e3bb172@oracle.com> Hello, On 4/9/2017 7:18 AM, Doug Lea wrote: > On 04/07/2017 10:56 PM, joe darcy wrote: >> Hello, >> >> Please review and comment on the the starter population of FAQ items >> below. These FAQ items generally do not deal with the logistics of using >> the CSR issue type; such items will be written after there is a public >> prototype of the CSR issue type. > > The only other questions I can think of are logistics related. > So, so far, it looks good to me! Thanks for taking this on. > Thanks for the comments on and off list. I've thought of another FAQ to include: Q: What are common types of feedback for the CSR to give? A: Common outcomes for a proposal after review by the CSR include: * Approved with no comments; this is most likely for small requests. * Deferring CSR review until additional technical reviewers examine the proposal. * Approving the proposal, but with comments affecting the code review. For example, the CSR may find issues with the javadoc that do not change the specification, etc. * Approving the proposal, on the condition that a release note is written for the change. * Substantive comments that require more extensive changes to the request. I plan to start populating the wiki with amended versions of the previously sent FAQ items. Thanks, -Joe From joe.darcy at oracle.com Tue Apr 11 18:45:42 2017 From: joe.darcy at oracle.com (joe darcy) Date: Tue, 11 Apr 2017 11:45:42 -0700 Subject: Initial CSR FAQ items In-Reply-To: <8613af88-c44c-e5f5-01bf-8b954e3bb172@oracle.com> References: <0bb7f08f-f047-f23b-01da-bdf32cfb59c6@oracle.com> <8613af88-c44c-e5f5-01bf-8b954e3bb172@oracle.com> Message-ID: <38a275ae-f225-557f-96b0-97d91db34c09@oracle.com> On 4/11/2017 11:24 AM, joe darcy wrote: > Hello, > > On 4/9/2017 7:18 AM, Doug Lea wrote: >> On 04/07/2017 10:56 PM, joe darcy wrote: >>> Hello, [snip] >>> > > I plan to start populating the wiki with amended versions of the > previously sent FAQ items. > FAQ page added: https://wiki.openjdk.java.net/display/csr/CSR+FAQs Cheers, -Joe From joe.darcy at oracle.com Tue Apr 11 19:00:36 2017 From: joe.darcy at oracle.com (joe darcy) Date: Tue, 11 Apr 2017 12:00:36 -0700 Subject: Welcome to CSR discuss, conversations on reviewing compatibility and specifications In-Reply-To: References: <26cff6c8-6847-2202-120c-e3df46250188@oracle.com> <58E7BC79.6040805@oracle.com> Message-ID: On 4/7/2017 1:24 PM, joe darcy wrote: > Hi Phil, > > On 4/7/2017 9:21 AM, Philip Race wrote: >> >> >On the logistics of accomplishing the above, I'd like to use the the >> wiki page for the CSR group >> >> > https://wiki.openjdk.java.net/display/csr/Main >> >> That is fine but we also should populate the group page with some >> information. >> I know that it can't be edited from outside but it looks pretty empty >> compared to most. > > Agreed; I'll update the page to state something like "Look at the wiki > instead of here." [snip] OpenJDK page for the CSR group, http://openjdk.java.net/groups/csr/, updated as described. -Joe From joe.darcy at oracle.com Wed Apr 12 21:14:34 2017 From: joe.darcy at oracle.com (joe darcy) Date: Wed, 12 Apr 2017 14:14:34 -0700 Subject: Fields of a CSR request Message-ID: <47a79bdc-fa19-e3a0-c27a-894345d9f623@oracle.com> Hello, While some finishing touches are being put on the on the CSR issue type in Jira, for your reviewing pleasure, below is a draft guide to the fields of CSR issue. In due time, I'll add this content as a page in the CSR wiki space. Thanks, -Joe A number of fields are common between the CSR issue type and normal bug/RFE issue types and between the CSR issue type and the JEP issue type. Unless otherwise noted, by default the fields in common among different issue types are used in analogous ways in each issue type with the field. Description: pre-populated with CSR template. The CSR template has four sections, Summary, Problem, Solution, and Specification. Follow the stated instructions on how to provide the requested information for each section. Assignee: the engineer who is currently the person primarily responsible for advancing the proposal. The assignee may change over time as different people work on the request. Priority: JIRA default field. Not used by the CSR process. Labels: Free-form text Component & Subcomponent: the technological area of the proposal; same classification scheme as used in the JDK project. If the proposal spans multiple areas, choose the area comprising the largest fraction of the proposal or break the proposal into multiple CSR issues. Status & Resolution: State of the proposal in the CSR process. There are five basic states captured in the Status field: Draft: In preparation by the assignee. The CSR members do not look at proposals in draft state. Proposed: The request is submitted for initial review by the CSR members. The proposal may be known to be incomplete, but early feedback from the CSR is being solicited. Going through this phase is recommend for large CSR requests to reduce the number of round-trips of CSR review. Provisional: After the CSR reviews a request that was proposed, if found to be acceptable the CSR chair moves the request to the Provisional state. A request in Provisional state is *not* ready to be pushed. It still needs further refinement and a second phase of CSR review. Finalized: In the opinion of the assignee, the proposal exactly as described is suitable for inclusion in the JDK. Closed/Approved: The CSR chair has approved the proposal for inclusion in the JDK. Proposals in this state can be pushed to a line of a development for a JDK release. Closed/Withdrawn: The assignee has chosen to not pursue further work on the proposal. Pended: The chair or other CSR member has identified an issue with the proposal that needs to be addressed before the proposal can be approved. Compatibility-related fields: Compatibility kind: check boxes for source, binary, and behavioral. Check which kinds of compatibility are impacted by this proposal. See https://wiki.openjdk.java.net/display/csr/Kinds+of+Compatibility for a detailed discussion on the different kinds of compatibility. Compatibility risk: minimal, low, medium, high Compatibility risk description: Issues with a compatibility risk of low, medium, or high should usually have a release note. Scope: Selection of SE, JDK, and Implementation. This field is shared with JEPs. SE -- Affects the Java SE API or platform specification, approximately the exported and public portions of java.* and javax.* JDK -- Affects the JDK-specific API or platform, including public and exported jdk.* APIs Implementation -- An implementation-only change that does not affect any specification. (Such a change will most likely have behavioral compatibility impact.) Reviewed by: The other engineers who have reviewed the request. At least one reviewer is required. The reviewers must include one or more engineers familiar with the components being modified by the request. CSR group members may serve as reviewers, but it is not mandatory to have a CSR member as a reviewer. Interface Kind: Java API, System property, Language construct, ... Check the boxes for which kinds of interfaces are affected by this request. Fix Version/s: The versions the proposal is targeted to change. For update releases, it is accepted to use one of the "pool" pseudo-release values such as "8-pool" to indicate some yet-to-be-determined release in the 8 update family. If known, a particular update release version may also be given. Attachments: Files related to the proposal, such as webrev.zip of specdiff representing the changes. Engineers are strongly encouraged to put bug numbers into into the file names that are attached. For example, for JDK-8123456 instead of attaching "webrev.zip" attach "8123456-webrev.zip". If the request is updated, leave any old attachments in place and attach updated versions (8123456-webrev.1.zip, etc.). The CSR members may want to compare versions of the proposals and verify requested changes were made. From dl at cs.oswego.edu Thu Apr 13 13:52:09 2017 From: dl at cs.oswego.edu (Doug Lea) Date: Thu, 13 Apr 2017 09:52:09 -0400 Subject: Fields of a CSR request In-Reply-To: <47a79bdc-fa19-e3a0-c27a-894345d9f623@oracle.com> References: <47a79bdc-fa19-e3a0-c27a-894345d9f623@oracle.com> Message-ID: <1761ce99-5f4a-62e4-aefa-0e964eafc7a2@cs.oswego.edu> On 04/12/2017 05:14 PM, joe darcy wrote: > Compatibility-related fields: > > Compatibility kind: check boxes for source, binary, and behavioral. > Check which kinds of compatibility are impacted by this proposal. See > https://wiki.openjdk.java.net/display/csr/Kinds+of+Compatibility for a > detailed discussion on the different kinds of compatibility. > > Compatibility risk: minimal, low, medium, high > > Compatibility risk description: Issues with a compatibility risk of low, > medium, or high should usually have a release note. It might be helpful to additionally categorize cases that arise, and the considerations that typically apply. Here's a first shot at some categories (but missing any associated considerations and criteria): 1. The old spec was unintentionally overly permissive -- it didn't rule out some behaviors, or was ambiguously worded or incomplete. (Implementations are unchanged.) 2. [Converse to 1] The old spec was overly restrictive, and did not allow reasonable/desirable implementation behavior. 3. The old spec contradicted implementation. The implementation was correct/desirable, so need to fix spec. 4. [Converse to 3] The old spec contradicted implementation. The implementation was incorrect/undesirable, but there is user code that relies on current implementation, so it is better to change spec. All four cases are crossed by whether the spec is part of an interface, class, or method that could be implemented or overridden externally to JDK. -Doug From joe.darcy at oracle.com Mon Apr 17 23:37:50 2017 From: joe.darcy at oracle.com (Joseph D. Darcy) Date: Mon, 17 Apr 2017 16:37:50 -0700 Subject: Fields of a CSR request In-Reply-To: <1761ce99-5f4a-62e4-aefa-0e964eafc7a2@cs.oswego.edu> References: <47a79bdc-fa19-e3a0-c27a-894345d9f623@oracle.com> <1761ce99-5f4a-62e4-aefa-0e964eafc7a2@cs.oswego.edu> Message-ID: <58F551CE.1070906@oracle.com> Hi Doug, On 4/13/2017 6:52 AM, Doug Lea wrote: > On 04/12/2017 05:14 PM, joe darcy wrote: >> Compatibility-related fields: >> >> Compatibility kind: check boxes for source, binary, and behavioral. >> Check which kinds of compatibility are impacted by this proposal. See >> https://wiki.openjdk.java.net/display/csr/Kinds+of+Compatibility for a >> detailed discussion on the different kinds of compatibility. >> >> Compatibility risk: minimal, low, medium, high >> >> Compatibility risk description: Issues with a compatibility risk of low, >> medium, or high should usually have a release note. > > It might be helpful to additionally categorize cases that arise, and > the considerations that typically apply. > > Here's a first shot at some categories (but missing any associated > considerations and criteria): > > 1. The old spec was unintentionally overly permissive -- it didn't > rule out some behaviors, or was ambiguously worded or incomplete. > (Implementations are unchanged.) > > 2. [Converse to 1] The old spec was overly restrictive, and did not > allow reasonable/desirable implementation behavior. > > 3. The old spec contradicted implementation. The implementation was > correct/desirable, so need to fix spec. > > 4. [Converse to 3] The old spec contradicted implementation. The > implementation was incorrect/undesirable, but there is user code that > relies on current implementation, so it is better to change spec. > > All four cases are crossed by whether the spec is part of an > interface, class, or method that could be implemented or overridden > externally to JDK. Worth noting that between cases 3 and 4, generally we follow case 3 in terms of resolving a conflict between the spec and implementation. That is, generally the spec is changed to match the implementation, especially if the implementation has been behaving in a certain way for several releases. There are exceptions to this of course. But, when it would be technically reasonable to change either the spec XOR the implementation, we prefer to change the spec, highlighting the importance of having solid specs and implementation to begin with! Thanks, -Joe From joe.darcy at oracle.com Tue Apr 18 23:36:02 2017 From: joe.darcy at oracle.com (joe darcy) Date: Tue, 18 Apr 2017 16:36:02 -0700 Subject: Draft: CSR Overview Message-ID: <1692227e-fa32-0649-0f12-1ed7429bdcb2@oracle.com> Hello, Please review the CSR overview paragraphs below. These are intended to be listed on the landing page of the CSR wiki space. Thanks to Brian for comments on previous drafts and for suggested edits. Cheers, -Joe CSR Overview The Java platform enjoys both breadth of use and longevity; over two decades after its introduction, it remains one of the most popular programming platforms. A core tenet of the Java platform has been the importance of high-quality specifications, specifications favoring precision, explicitness, and completeness. The Java language, virtual machine, and API specifications are foundational documents for the Java ecosystem. The precision of these specifications, combined with a strong commitment to cross-release compatibly, allows applications and libraries to generally "just work" across releases. A key component to ensuring and maintaining the quality of the specification was the "CCC" process, originated at Sun, which was dedicated to looking after compatibility and specification concerns, aiming to balance stability with progress and help keep Java vibrant. The role played by the CCC process has now been transferred to the Compatibility & Specification Review (CSR) OpenJDK group, providing transparency and ensuring wider community input. The primary role of the CSR group is to review all changes to the JDK's exported interfaces, interfaces meaning the general protocol between the JDK and users of the JDK. This review typically focuses on specification changes. However, implementation-only changes may also merit review if they have sufficiently large behavioral compatibility impact. Secondarily, the CSR is also a resource to provide feedback to engineers working on Java platform APIs. The CSR process fulfills an archival function as well, keeping stand-alone record of API and interface changes. From david.holmes at oracle.com Tue Apr 18 23:49:38 2017 From: david.holmes at oracle.com (David Holmes) Date: Wed, 19 Apr 2017 09:49:38 +1000 Subject: Draft: CSR Overview In-Reply-To: <1692227e-fa32-0649-0f12-1ed7429bdcb2@oracle.com> References: <1692227e-fa32-0649-0f12-1ed7429bdcb2@oracle.com> Message-ID: <8c831e92-bbe7-9241-e1a0-0e033815b2e7@oracle.com> Hi Joe, Generally reads well. Two minor comments ... On 19/04/2017 9:36 AM, joe darcy wrote: > Hello, > > Please review the CSR overview paragraphs below. These are intended to > be listed on the landing page of the CSR wiki space. > > Thanks to Brian for comments on previous drafts and for suggested edits. > > Cheers, > > -Joe > > CSR Overview > > The Java platform enjoys both breadth of use and longevity; over two > decades after its introduction, it remains one of the most popular > programming platforms. A core tenet of the Java platform has been the > importance of high-quality specifications, specifications favoring > precision, explicitness, and completeness. The Java language, virtual > machine, and API specifications are foundational documents for the Java > ecosystem. The precision of these specifications, combined with a strong > commitment to cross-release compatibly, allows applications and > libraries to generally "just work" across releases. > > A key component to ensuring and maintaining the quality of the > specification was the "CCC" process, originated at Sun, which was > dedicated to looking after compatibility and specification concerns, > aiming to balance stability with progress and help keep Java vibrant. > The role played by the CCC process has now been transferred to the > Compatibility & Specification Review (CSR) OpenJDK group, providing > transparency and ensuring wider community input. > > The primary role of the CSR group is to review all changes to the JDK's > exported interfaces, interfaces meaning the general protocol between the > JDK and users of the JDK. The above sentence does not read correctly to me. And is it a protocol or a contract? > This review typically focuses on specification > changes. However, implementation-only changes may also merit review if > they have sufficiently large behavioral compatibility impact. > Secondarily, the CSR is also a resource to provide feedback to engineers > working on Java platform APIs. The CSR process fulfills an archival > function as well, keeping stand-alone record of API and interface changes. s/record/records/ Thanks, David > From joe.darcy at oracle.com Tue Apr 18 23:56:56 2017 From: joe.darcy at oracle.com (joe darcy) Date: Tue, 18 Apr 2017 16:56:56 -0700 Subject: Draft: CSR Overview In-Reply-To: <8c831e92-bbe7-9241-e1a0-0e033815b2e7@oracle.com> References: <1692227e-fa32-0649-0f12-1ed7429bdcb2@oracle.com> <8c831e92-bbe7-9241-e1a0-0e033815b2e7@oracle.com> Message-ID: <6291e727-408c-4d47-b6c5-13c2da6f9747@oracle.com> Hi David, On 4/18/2017 4:49 PM, David Holmes wrote: > Hi Joe, > > Generally reads well. Two minor comments ... > > On 19/04/2017 9:36 AM, joe darcy wrote: >> Hello, >> >> Please review the CSR overview paragraphs below. These are intended to >> be listed on the landing page of the CSR wiki space. >> >> Thanks to Brian for comments on previous drafts and for suggested edits. >> >> Cheers, >> >> -Joe >> >> CSR Overview >> >> The Java platform enjoys both breadth of use and longevity; over two >> decades after its introduction, it remains one of the most popular >> programming platforms. A core tenet of the Java platform has been the >> importance of high-quality specifications, specifications favoring >> precision, explicitness, and completeness. The Java language, virtual >> machine, and API specifications are foundational documents for the Java >> ecosystem. The precision of these specifications, combined with a strong >> commitment to cross-release compatibly, allows applications and >> libraries to generally "just work" across releases. >> >> A key component to ensuring and maintaining the quality of the >> specification was the "CCC" process, originated at Sun, which was >> dedicated to looking after compatibility and specification concerns, >> aiming to balance stability with progress and help keep Java vibrant. >> The role played by the CCC process has now been transferred to the >> Compatibility & Specification Review (CSR) OpenJDK group, providing >> transparency and ensuring wider community input. >> >> The primary role of the CSR group is to review all changes to the JDK's >> exported interfaces, interfaces meaning the general protocol between the >> JDK and users of the JDK. > > The above sentence does not read correctly to me. And is it a protocol > or a contract? The term "contract" in the sense of "the technical contract for users of the JDK" is the meaning I wanted to convey. However, I used the term "protocol" because it has a more technical connotation and has more semantic distance from "contract" in the sense of licensing terms. Perhaps "general protocol" would be better as "general sets of protocols". > >> This review typically focuses on specification >> changes. However, implementation-only changes may also merit review if >> they have sufficiently large behavioral compatibility impact. >> Secondarily, the CSR is also a resource to provide feedback to engineers >> working on Java platform APIs. The CSR process fulfills an archival >> function as well, keeping stand-alone record of API and interface >> changes. > > s/record/records/ > ACK; will fix before adding to the wiki. Thanks, -Joe From philip.race at oracle.com Wed Apr 19 00:05:26 2017 From: philip.race at oracle.com (Philip Race) Date: Tue, 18 Apr 2017 17:05:26 -0700 Subject: Draft: CSR Overview In-Reply-To: <1692227e-fa32-0649-0f12-1ed7429bdcb2@oracle.com> References: <1692227e-fa32-0649-0f12-1ed7429bdcb2@oracle.com> Message-ID: <58F6A9C6.9090306@oracle.com> On 4/18/17, 4:36 PM, joe darcy wrote: > However, implementation-only changes may also merit review if they > have sufficiently large behavioral how about "large or broad" ? > compatibility impact. Secondarily, the CSR is also a resource to > provide feedback to engineers working on Java > platform APIs. The CSR process fulfills an archival function as well, > keeping stand-alone record of API and ^ "a" stand-alone record ? > interface changes. -phil. From david.holmes at oracle.com Wed Apr 19 00:09:18 2017 From: david.holmes at oracle.com (David Holmes) Date: Wed, 19 Apr 2017 10:09:18 +1000 Subject: Draft: CSR Overview In-Reply-To: <6291e727-408c-4d47-b6c5-13c2da6f9747@oracle.com> References: <1692227e-fa32-0649-0f12-1ed7429bdcb2@oracle.com> <8c831e92-bbe7-9241-e1a0-0e033815b2e7@oracle.com> <6291e727-408c-4d47-b6c5-13c2da6f9747@oracle.com> Message-ID: On 19/04/2017 9:56 AM, joe darcy wrote: > Hi David, > > > On 4/18/2017 4:49 PM, David Holmes wrote: >> Hi Joe, >> >> Generally reads well. Two minor comments ... >> >> On 19/04/2017 9:36 AM, joe darcy wrote: >>> Hello, >>> >>> Please review the CSR overview paragraphs below. These are intended to >>> be listed on the landing page of the CSR wiki space. >>> >>> Thanks to Brian for comments on previous drafts and for suggested edits. >>> >>> Cheers, >>> >>> -Joe >>> >>> CSR Overview >>> >>> The Java platform enjoys both breadth of use and longevity; over two >>> decades after its introduction, it remains one of the most popular >>> programming platforms. A core tenet of the Java platform has been the >>> importance of high-quality specifications, specifications favoring >>> precision, explicitness, and completeness. The Java language, virtual >>> machine, and API specifications are foundational documents for the Java >>> ecosystem. The precision of these specifications, combined with a strong >>> commitment to cross-release compatibly, allows applications and >>> libraries to generally "just work" across releases. >>> >>> A key component to ensuring and maintaining the quality of the >>> specification was the "CCC" process, originated at Sun, which was >>> dedicated to looking after compatibility and specification concerns, >>> aiming to balance stability with progress and help keep Java vibrant. >>> The role played by the CCC process has now been transferred to the >>> Compatibility & Specification Review (CSR) OpenJDK group, providing >>> transparency and ensuring wider community input. >>> >>> The primary role of the CSR group is to review all changes to the JDK's >>> exported interfaces, interfaces meaning the general protocol between the >>> JDK and users of the JDK. >> >> The above sentence does not read correctly to me. And is it a protocol >> or a contract? > > The term "contract" in the sense of "the technical contract for users of > the JDK" is the meaning I wanted to convey. However, I used the term > "protocol" because it has a more technical connotation and has more > semantic distance from "contract" in the sense of licensing terms. > > Perhaps "general protocol" would be better as "general sets of protocols". Ok. But the sentence structure is still problematic for me. Not sure whether it just needs a semi-colon instead of a comma, or two distinct sentences. Cheers, David >> >>> This review typically focuses on specification >>> changes. However, implementation-only changes may also merit review if >>> they have sufficiently large behavioral compatibility impact. >>> Secondarily, the CSR is also a resource to provide feedback to engineers >>> working on Java platform APIs. The CSR process fulfills an archival >>> function as well, keeping stand-alone record of API and interface >>> changes. >> >> s/record/records/ >> > > ACK; will fix before adding to the wiki. > > Thanks, > > -Joe From dalibor.topic at oracle.com Wed Apr 19 09:22:16 2017 From: dalibor.topic at oracle.com (dalibor topic) Date: Wed, 19 Apr 2017 11:22:16 +0200 Subject: Draft: CSR Overview In-Reply-To: <1692227e-fa32-0649-0f12-1ed7429bdcb2@oracle.com> References: <1692227e-fa32-0649-0f12-1ed7429bdcb2@oracle.com> Message-ID: On 19.04.2017 01:36, joe darcy wrote: Thanks Joe, this reads well. I have just a few small suggestions: > The Java platform enjoys both breadth of use and longevity; over two > decades after its introduction, it remains one of the most popular > programming platforms. I'd suggest dropping the 'two decades' part of the sentence here as it seems to restate the first part in different words. > ecosystem. The precision of these specifications, combined with a strong > commitment to cross-release compatibly, '... to compatibility' might read a bit better, although the meaning is slightly different, of course. But as the rest of the sentence already says 'across releases' it sounds like a bit of repetition otherwise. > A key component to ensuring and maintaining the quality of the > specification was the "CCC" process, originated at Sun, which was I'd suggest using the long form 'Sun Microsystems' here. While 'Sun' is still a convenient short form, its convenience might disappear over time. > The role played by the CCC process has now been transferred to the > Compatibility & Specification Review (CSR) OpenJDK group, providing Group, as an OpenJDK organizational concept, should be upper cased, as in 'OpenJDK Group'. > The primary role of the CSR group is to review all changes to the JDK's Group, as an OpenJDK organizational concept, should be upper cased, as in 'CSR Group'. cheers, dalibor topic -- Dalibor Topic | Principal Product Manager Phone: +494089091214 | Mobile: +491737185961 ORACLE Deutschland B.V. & Co. KG | K?hneh?fe 5 | 22761 Hamburg ORACLE Deutschland B.V. & Co. KG Hauptverwaltung: Riesstr. 25, D-80992 M?nchen Registergericht: Amtsgericht M?nchen, HRA 95603 Komplement?rin: ORACLE Deutschland Verwaltung B.V. Hertogswetering 163/167, 3543 AS Utrecht, Niederlande Handelsregister der Handelskammer Midden-Niederlande, Nr. 30143697 Gesch?ftsf?hrer: Alexander van der Ven, Jan Schultheiss, Val Maher Oracle is committed to developing practices and products that help protect the environment From joe.darcy at oracle.com Wed Apr 19 23:24:53 2017 From: joe.darcy at oracle.com (Joseph D. Darcy) Date: Wed, 19 Apr 2017 16:24:53 -0700 Subject: Draft: CSR Overview In-Reply-To: References: <1692227e-fa32-0649-0f12-1ed7429bdcb2@oracle.com> Message-ID: <58F7F1C5.9070803@oracle.com> Thanks all for the feedback. Edited paragraphs added to the wiki. Cheers, -Joe On 4/19/2017 2:22 AM, dalibor topic wrote: > On 19.04.2017 01:36, joe darcy wrote: > > Thanks Joe, this reads well. I have just a few small suggestions: > >> The Java platform enjoys both breadth of use and longevity; over two >> decades after its introduction, it remains one of the most popular >> programming platforms. > > I'd suggest dropping the 'two decades' part of the sentence here as it > seems to restate the first part in different words. > >> ecosystem. The precision of these specifications, combined with a strong >> commitment to cross-release compatibly, > > '... to compatibility' might read a bit better, although the meaning > is slightly different, of course. But as the rest of the sentence > already says 'across releases' it sounds like a bit of repetition > otherwise. > >> A key component to ensuring and maintaining the quality of the >> specification was the "CCC" process, originated at Sun, which was > > I'd suggest using the long form 'Sun Microsystems' here. While 'Sun' > is still a convenient short form, its convenience might disappear over > time. > >> The role played by the CCC process has now been transferred to the >> Compatibility & Specification Review (CSR) OpenJDK group, providing > > Group, as an OpenJDK organizational concept, should be upper cased, as > in 'OpenJDK Group'. > >> The primary role of the CSR group is to review all changes to the JDK's > > Group, as an OpenJDK organizational concept, should be upper cased, as > in 'CSR Group'. > > cheers, > dalibor topic > From joe.darcy at oracle.com Thu Apr 20 00:09:57 2017 From: joe.darcy at oracle.com (Joseph D. Darcy) Date: Wed, 19 Apr 2017 17:09:57 -0700 Subject: Fields of a CSR request In-Reply-To: <58F551CE.1070906@oracle.com> References: <47a79bdc-fa19-e3a0-c27a-894345d9f623@oracle.com> <1761ce99-5f4a-62e4-aefa-0e964eafc7a2@cs.oswego.edu> <58F551CE.1070906@oracle.com> Message-ID: <58F7FC55.1010802@oracle.com> PS Added a FAQ item on how to handle a discrepancy between the specification and implementation: https://wiki.openjdk.java.net/display/csr/CSR+FAQs -Joe On 4/17/2017 4:37 PM, Joseph D. Darcy wrote: > Hi Doug, > > On 4/13/2017 6:52 AM, Doug Lea wrote: >> On 04/12/2017 05:14 PM, joe darcy wrote: >> [snip] >> >> 3. The old spec contradicted implementation. The implementation was >> correct/desirable, so need to fix spec. >> >> 4. [Converse to 3] The old spec contradicted implementation. The >> implementation was incorrect/undesirable, but there is user code that >> relies on current implementation, so it is better to change spec. >> >> All four cases are crossed by whether the spec is part of an >> interface, class, or method that could be implemented or overridden >> externally to JDK. > > Worth noting that between cases 3 and 4, generally we follow case 3 in > terms of resolving a conflict between the spec and implementation. > That is, generally the spec is changed to match the implementation, > especially if the implementation has been behaving in a certain way > for several releases. There are exceptions to this of course. But, > when it would be technically reasonable to change either the spec XOR > the implementation, we prefer to change the spec, highlighting the > importance of having solid specs and implementation to begin with! > > From joe.darcy at oracle.com Thu Apr 20 16:42:07 2017 From: joe.darcy at oracle.com (joe darcy) Date: Thu, 20 Apr 2017 09:42:07 -0700 Subject: CSR FAQ item on deprecation Message-ID: <7b3f7c48-3fb9-122a-9d30-62e642be9bd9@oracle.com> Paging Dr. Deprecator! Consultation on deprecation needed; please review the draft CSR FAQ item on deprecation. Thanks, -Joe Q: What is the JDK's policy on deprecating items? A: As of JDK 9, JDK APIs use enhanced deprecation (http://openjdk.java.net/jeps/277). In summary, if an API is problematic in one or more ways, it can be marked as @Deprecated to discourage its use. If there are plans to remove the API in the following release, then it should be marked as @Deprecated(forRemoval=true). If an item is deprecated for removal in the next release, the bug to implement the removal should be filed by the time the CSR request is approved. Deprecated items should have a corresponding @deprecated javadoc tag. From stuart.marks at oracle.com Fri Apr 21 19:48:37 2017 From: stuart.marks at oracle.com (Stuart Marks) Date: Fri, 21 Apr 2017 12:48:37 -0700 Subject: CSR FAQ item on deprecation In-Reply-To: <7b3f7c48-3fb9-122a-9d30-62e642be9bd9@oracle.com> References: <7b3f7c48-3fb9-122a-9d30-62e642be9bd9@oracle.com> Message-ID: On 4/20/17 9:42 AM, joe darcy wrote: > Paging Dr. Deprecator! > > Consultation on deprecation needed; please review the draft CSR FAQ item on > deprecation. > > Thanks, > > -Joe > > Q: What is the JDK's policy on deprecating items? > A: As of JDK 9, JDK APIs use enhanced deprecation > (http://openjdk.java.net/jeps/277). In summary, if an API is problematic in one > or more ways, it can be marked as @Deprecated to discourage its use. If there > are plans to remove the API in the following release, then it should be marked > as @Deprecated(forRemoval=true). If an item is deprecated for removal in the > next release, the bug to implement the removal should be filed by the time the > CSR request is approved. Deprecated items should have a corresponding > @deprecated javadoc tag. Hi Joe, This is a pretty good answer. I'd only add that the text for the @deprecated javadoc tag should include a recommendation for a replacement API, and any potential issues (e.g., semantic differences) with substituting it. s'marks From joe.darcy at oracle.com Fri Apr 21 20:09:29 2017 From: joe.darcy at oracle.com (Joseph D. Darcy) Date: Fri, 21 Apr 2017 13:09:29 -0700 Subject: CSR FAQ item on deprecation In-Reply-To: References: <7b3f7c48-3fb9-122a-9d30-62e642be9bd9@oracle.com> Message-ID: <58FA66F9.6020901@oracle.com> On 4/21/2017 12:48 PM, Stuart Marks wrote: > On 4/20/17 9:42 AM, joe darcy wrote: >> Paging Dr. Deprecator! >> >> Consultation on deprecation needed; please review the draft CSR FAQ >> item on >> deprecation. >> >> Thanks, >> >> -Joe >> >> Q: What is the JDK's policy on deprecating items? >> A: As of JDK 9, JDK APIs use enhanced deprecation >> (http://openjdk.java.net/jeps/277). In summary, if an API is >> problematic in one >> or more ways, it can be marked as @Deprecated to discourage its use. >> If there >> are plans to remove the API in the following release, then it should >> be marked >> as @Deprecated(forRemoval=true). If an item is deprecated for removal >> in the >> next release, the bug to implement the removal should be filed by the >> time the >> CSR request is approved. Deprecated items should have a corresponding >> @deprecated javadoc tag. > > Hi Joe, > > This is a pretty good answer. I'd only add that the text for the > @deprecated javadoc tag should include a recommendation for a > replacement API, and any potential issues (e.g., semantic differences) > with substituting it. > > s'marks Thanks Stuart; suggested notes on @deprecated added. Cheers, -Joe From joe.darcy at oracle.com Mon Apr 24 17:12:11 2017 From: joe.darcy at oracle.com (joe darcy) Date: Mon, 24 Apr 2017 10:12:11 -0700 Subject: General JDK Compatibility Policy Message-ID: Hello, Continuing to populate the CSR wiki, please review the proposed General JDK Compatibility Policy: The general compatibility policy for exported APIs implemented in the JDK is: * Don't break binary compatibility (as defined in the Java Language Specification) without sufficient cause. * Avoid introducing source incompatibilities. * Manage behavioral compatibility changes. One sufficient cause for breaking binary compatibility is removing a an API deprecated for removal in an earlier release, as described in the enhanced deprecation policy (http://openjdk.java.net/jeps/277). The different kinds of compatibility can be subtle and are discussed in detail elsewhere (https://wiki.openjdk.java.net/display/csr/Kinds+of+Compatibility). This will appear after the "CSR Background and Overview" on the main page. Thanks, -Joe From joe.darcy at oracle.com Wed Apr 26 18:22:21 2017 From: joe.darcy at oracle.com (joe darcy) Date: Wed, 26 Apr 2017 11:22:21 -0700 Subject: General JDK Compatibility Policy In-Reply-To: References: Message-ID: <3f5d8ee0-4e93-7d63-6426-4f7dc11ae6af@oracle.com> On 4/24/2017 10:12 AM, joe darcy wrote: > Hello, > > Continuing to populate the CSR wiki, please review the proposed > General JDK Compatibility Policy: > Wiki updated. Cheers, -Joe From joe.darcy at oracle.com Thu Apr 27 03:58:36 2017 From: joe.darcy at oracle.com (joe darcy) Date: Wed, 26 Apr 2017 20:58:36 -0700 Subject: FYI, bugs.openjdk.java.net changes to support CSR coming soon Message-ID: <6e77ce51-d291-4cf8-d711-d62c2ff1e152@oracle.com> Hello, FYI, some maintenance [1] of bugs.openjdk.java.net is scheduled for May 2, 2017 to support the CSR issue type. Publication of sample CSR issues as imported ccc requests from JDK 9 expected later in that week. Cheers, -Joe [1] http://mail.openjdk.java.net/pipermail/announce/2017-April/000228.html