Draft: CSR Overview

[joe darcy]

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