Initial CSR FAQ items

[joe darcy]

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.