err

Author: liach

_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 行为兼容
+
+比较常见。比如以前不报错现在报错，报错种类不同，返回值变化，能接收的参数种类更广这样的。
+
+ 
+
+<script src="https://giscus.app/client.js"
+        data-repo="liachmodded/liachmodded.github.io"
+        data-repo-id="MDEwOlJlcG9zaXRvcnkxMTU2NzU0Mjc="
+        data-category="Announcements"
+        data-category-id="DIC_kwDOBuURI84CfnKT"
+        data-mapping="pathname"
+        data-strict="0"
+        data-reactions-enabled="0"
+        data-emit-metadata="1"
+        data-input-position="top"
+        data-theme="preferred_color_scheme"
+        data-lang="en"
+        data-loading="lazy"
+        crossorigin="anonymous"
+        async>
+</script>