From f752aaaadbf18677b2fc4cf610c3edbbad81eb9c Mon Sep 17 00:00:00 2001 From: liach Date: Fri, 4 Oct 2024 09:49:46 -0500 Subject: [PATCH] err --- _posts/2024-10-04-csr.md | 90 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 _posts/2024-10-04-csr.md diff --git a/_posts/2024-10-04-csr.md b/_posts/2024-10-04-csr.md new file mode 100644 index 0000000..cf7a36c --- /dev/null +++ b/_posts/2024-10-04-csr.md @@ -0,0 +1,90 @@ +--- +layout: post +title: "JDK 的 CSR" +categories: java +tags: CSR +--- + +--- + +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](https://wiki.openjdk.org/display/csr/Fields+of+a+CSR+Request) + +- 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 行为兼容 + +比较常见。比如以前不报错现在报错，报错种类不同，返回值变化，能接收的参数种类更广这样的。 + + + +