proposal: add bug fix tracing strategy for version releasing

Author: liucf3995

proposal/A1-bug-fix-tracing.zh_CN.md

@@ -0,0 +1,236 @@
+[English](A1-bug-fix-tracing.md) | 中文
+
+# 标题
+
+* 作者：liucf3995
+* 批准者：
+* 状态：草案
+* 已实现的语言：
+* 上次更新时间：2023-10-26
+* 讨论链接：
+
+## 目录
+
+* [概要](#概要)
+* [背景](#背景)
+    * [相关提案](#相关提案)
+* [设计细节](#设计细节)
+* [实现细节](#实现细节)
+* [业界实现](#业界实现)
+* [其他问题](#其他问题)
+
+## 概要
+
+在 tRPC 代码仓库版本发布时，为 Bug 修复情况提供跟踪策略。
+
+## 背景
+
+tRPC 当前的 ChangeLog 会提示每个版本新增的 Features 以及修复的 Bugs，但是未提供 Bug 跟踪信息。
+即，用户在选择 tRPC 版本时，可以得知所选版本已经解决了哪些 Bugs，但是无法得知还有哪些 Bugs 未解决。
+
+目标：定义框架发布版本时 ChangeLog 中 BugFix 的规范格式，然后通过自动化的工具提取数据后，用户可以在 tRPC 官网上通过选择 tRPC
+的某个具体版本后，除了看到这个版本修复了哪些 Bugs，还可以看到这个版本存在哪些 Bugs。
+
+例如：选择 `trpc-cpp/v1.4.2`，页面提示如下内容：
+
+  ```text
+  已修复 Bugs：
+  Bug-01(#PR): Bug 描述。从 v1.1.0 引入，在 v1.4.2 修复。
+  Bug-02(#PR): Bug 描述。从 v1.1.1 引入，在 v1.4.2 修复。
+  ...
+  
+  未修复 Bugs：
+  Bug-01(#PR): Bug 描述。从 v1.1.0 引入。
+  Bug-02(#PR): Bug 描述，从 v2.1.0 发现，引入版本号未知。
+  ...
+  ```
+
+在报告 Bug 时，如果知道引入 Bug 的准确版本号，则提示 Bug 引入版本号。如果无法得知 Bug 引入的准确版本号，则标记 “Bug
+发现版本号，引入版本号未知”。
+
+### 相关提案
+
+暂无其他相关提案。
+
+## 设计细节
+
+主要借助 Issue 和 ChangeLog 两部分信息记录 Bug 修复信息。
+
+* 所有的 Bug 信息通过 Issue 来跟踪，通过 Issue 关闭和打开的状态区分未修复 Bug 清单（未关闭的 Bug Issue）。
+* ChangeLog 记录 Bug 引入版本号、修复版本号（一般是当前版本号）、关联的 #PR。同时，PR 中也记录已被修复 Bug 的 #Issue 和引入版本号。
+
+## 实现细节
+
+### 如何跟踪 Bug 信息
+
+所有的 Bugs 均通过 Issues 来跟踪。
+
+* 开发者在修复 Bug 时，及时关闭对应的 Issue。
+* 管理员在发布版本时，在 ChangeLog 准确记录被修复的 Bugs 信息。
+ 
+推荐（可选）：提交 Issue 时，Issue 正文包含 Bug 引入版本号或者发现版本号。
+
+### 如何确认 Bug 引入版本号和修复版本号
+
+用户在报告 Bug 时，一般会提供自己所使用的版本号，但这个版本号可能并非 Bug 最早引入的版本号。所以，单从 Issue 信息可能无法得知
+Bug 引入时机。可将 Issue 报告的版本号作为默认的版本号，等后续修复时，可以更新 Bug 引入的具体版本号。
+
+Bug 修复版本号由 ChangeLog 发版记录标识。
+
+### 如何编辑 ChangeLog#BugFix 条目
+
+已修复 Bug 基本格式：Bug 影响范围 + Bug描述 + (!#PR) + (Bug 引入版本范围)。
+
+Bug 引入版本范围：
+
+* v1.2.0：由 v1.2.0 引入。
+* v1.2.0~v1.4.0：v1.2.0 ~ v1.4.0 某个版本引入，具体版本号未知。
+* v1.1.0~：1.1.0 ~ 修复版本之间的某个版本引入，具体版本号未知。
+* ~v2.2.0：起始版本 ~ v1.2.0 之间某个版本引入，具体版本号未知。
+
+```markdown
+...
+
+## [$current_version](url)($release_date)
+
+...
+
+### Bug Fixes 
+- **$scope:** $prompt (!#PR) ($version)
+- **$scope:** $prompt (!#PR) ($version_begin~$version_end)
+- **$scope:** $prompt (!#PR) (~$version_end)
+- **$scope:** $prompt (!#PR) ($version_begin~)
+
+...
+```
+
+### 如何计算 Bugs 修复结果
+
+解析 ChangeLog#BugFixes 记录，得到如下数据：
+* 已修复 Bug 的引入版本号范围、修复版本号、#PR 。
+
+计算某个具体版本下 Bugs 修复情况。
+* 当前版本已修复 Bugs：过滤 Bug 修复版本号为当前版本号的已修复 Bugs。
+* 当前版本未修复 Bugs：从已修复的所有 Bugs 中过滤，条件：当前版本号在 Bug 引入版本号（或者发现版本号）范围内。
+
+
+### 举例说明
+
+管理员依据 Bug Issue + PR 列表记录 ChangeLog。
+
+* Bug Issue 列表（Closed）：
+
+  ```text
+  [#1] xx
+  
+  version: v1.1.0
+  
+  ///////////////////////////////////////
+  
+  [#2] yy
+  
+  version: v1.2.0
+  
+  ///////////////////////////////////////
+  
+  [#3] zz
+  
+  version: v1.3.0
+  ```
+
+* Bug Issue 列表（Open）：
+
+  ```text
+  [#4] xx
+  
+  version: v1.1.1
+  
+  ///////////////////////////////////////
+  
+  [#5] yy
+  
+  version: v1.2.1
+  
+  ///////////////////////////////////////
+  
+  [#6] zz
+  
+  version: v1.3.1
+  ```
+  
+* PR 列表（Merged）： 
+ 
+  ```text
+  [#7] xx
+  
+  close #1 
+  
+  ///////////////////////////////////////
+  
+  [#8] yy
+  
+  close #2 
+  
+  ///////////////////////////////////////
+  
+  [#9] zz 
+  
+  close #3 
+  ```
+
+* ChangeLog:
+
+  ```markdown
+  
+  ## [v1.3.1](https://github.com/xx/yy)(2023-10-19)
+  ...
+  ### Bug Fixes 
+  - **stream:** yy (!8) (v1.2.0)
+  - **client:** zz (!9) (v1.3.0)
+  
+  ...
+  
+  ## [v1.2.1](https://github.com/xx/yy)(2023-09-19)
+  ...
+  ### Bug Fixes
+  - **transport:** yy (!7) (1.2.0)
+ 
+  ...
+  ```
+
+选择某个具体版本后，提示已修复 Bugs 信息和未修复 Bugs 信息。
+
+提示：Issue 列表中还未被修复的 Bugs 不会展示出来。
+
+* 选择 v1.3.1 时，提示：
+
+  ```text
+  已修复 Bugs：
+  Bug-02(#8): yy。从 v1.2.0 引入，在 v1.3.1 修复。 
+  Bug-03(#9): zz。从 v1.3.0 引入, 在 v1.3.1 修复。 
+  
+  ```
+
+* 选择 v1.2.1 时，提示：
+
+  ```text
+  已修复 Bugs：
+  Bug-01(#7): xx。从 v1.1.0 发现，在 v1.2.1 修复。 
+  
+  未修复 Bugs：
+  Bug-02(#8): yy。从 v1.2.0 引入，在 v1.3.1 修复。 
+  ```
+
+## 业界实现
+
+暂无
+
+## 其他问题
+
+可以跟踪 Bug 从某个一个版本引入，另外一个版本修复时的情况。无法跟踪一个 Bug 从多个版本引入和修复信息。
+比如，Bug-A 从 v1.1.0 引入，然后在 v1.1.3 修复。后来相同的 Bug 又在 v1.2.0 引入，在 v1.2.1 修复。
+这种情况下需要创建两个 Bug 来标识。
+
+页面展示的 Bugs 信息中只包含已修复的 Bugs，Issue 列表中当前还未被修复的 Bugs 不会展示出来。
+
+对历史已经存在 ChangeLog 和 Issue 记录可能无法解析，需要解析工具做兼容。