Note: This page is still under construction

CSR 意为兼容性和定义复核，是改动 JDK 接口必须经过的一个流程。这个流程相当于对接口和被依赖的行为的品控，避免对 Java 平台的一些改动带来过大恶果。

大致流程

  • 提交主补丁，确定改动的 Javadoc 和 API 定义
  • 在主 issue 下 More -> Create CSR，然后填写 CSR
  • 别人审核批准补丁也会审核批准你的 CSR，算工程师批准
  • CSR 获得工程师批准后从草稿状态转定稿
  • 等 CSR 领头批准。
    • 批准时可能会提其他要求，比如改一些词汇或者写更新日志，不要忘
    • 有可能变临时，需要你回复疑问或者修改，然后重新转定稿，等下一轮批准
    • 批准后又对 Javadoc 或者 API 定义改动，则需要重新转草稿修改，然后再转定稿重新批准！
  • CSR 通过后可以合并补丁

CSR 格式

CSR 都有主 issue。在主 issue 中选择 More -> Create CSR 即可创建空模板的新 CSR。

格式原文可参见 wiki

  • Description 介绍：文字部分分４块，Summary 总结、Problem 问题、Solution 方案、Specificaiton 定义。
    • 总结：简单概括改动的主旨，比如添加新字段方法
    • 问题：列举下需要改动的理由，比如某些值常用但是直接写常量容易出错，最好用字段常量等，或者某些方法很常用，同时 JDK 能提供的实现比用户自己实现的更好
    • 方案：列举下具体的改动。有时候也可以列举下其他方案，然后为什么不采用其他方案等
    • 定义：定义变动。一般 Javadoc 都算定义，除了 @apiNote @implNote，然后接口类型字段加减也算。一般上传 git diff 但是移除非接口和定义改动。
  • Assignee 负责人：只有负责人能够推进 CSR 的状态
  • Component/Subcomponent：和主 issue 相同
  • Status 状态：
    • Draft 草稿：刚创建的初始状态。
    • Proposed 提议：告诉 CSR 希望获得早期审核，一般会给反馈后进临时。
    • Provisional 临时：审核后的状态。记得回复或者进行改动，然后重新进终稿！
    • Finalized 定稿：有了工程师批准后其他状态才可以进定稿。只有定稿才能被批准。
    • Closed/Appoved 批准：批准了，可以提交改动。
    • Closed/Withdrawn 撤回：补丁被抛弃，或者不需要 CSR。
  • Compatibility Kind 兼容性种类：source 编译兼容性、binary 字节码运行兼容性、behavioral 行为兼容性
  • Compatibility Risk 兼容性风险等级
  • Compatibility Risk Description 兼容性风险介绍：介绍具体兼容风险和为什么评某个等级
  • Reviewed By 工程师批准：有了工程师批准后才能定稿提交 CSR 去被批准。
  • Scope 范围：一般是 java. 模块是 SE，jdk. 模块是 JDK，对接口没影响的一般算 Implementation。
  • Interface Kind 接口种类：打勾，一般核心库是 Java API。
  • Fix Version/s 修复版本：必须提前选择，补丁针对的版本。没正确版本 CSR 不会审核！
  • Attachments 附件：一般定义变动的 git diff 太大可以用附件上传。

兼容性种类

一般 API 修改会编译和字节码运行都会有兼容考量，但是有些特例。

Source 编译兼容

之前 Sequenced Collection 破坏编译兼容，同时实现List和Deque的类无法继续编译，reverse。但是运行时因为两个reverse字节码签名不同，老版本实现可以继续正常跑。

Binary 字节码运行兼容

比如一个方法，返回从Object变String。编译还是没问题，返回值完全兼容，但是字节码签名变了，老版本下游依赖不能用这个新方法，老方法被移除了。

Behavioral 行为兼容

比较常见。比如以前不报错现在报错，报错种类不同，返回值变化，能接收的参数种类更广这样的。