Page History

...

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 size 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 responsible for factoring in reasonable amount of time for a CSR review ahead of any integration deadline, anticipating that the CSR might have feedback which requires the proposal to be updated. While engineers are free to request an expedited review from the CSR, 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 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, 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 JDK's policy on deprecating items?
A: As of JDK 9, JDK APIs use enhanced deprecation. 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. The @deprecated text should include a reference to a recommended replacement API, if one exists, and note any salient semantic differences with a replacement.

Q: What is the relationship between a CSR and a JEP?
A: A JEP (JDK Enhancement-Proposal) 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.

...