From 38aa25746d16e8b9c557fd0064904c5a873db8c1 Mon Sep 17 00:00:00 2001 From: liucf3995 Date: Fri, 20 Oct 2023 13:24:37 +0800 Subject: [PATCH] proposal: add bug fix tracing strategy for version releasing --- proposal/A1-bug-fix-tracing.zh_CN.md | 236 +++++++++++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 proposal/A1-bug-fix-tracing.zh_CN.md diff --git a/proposal/A1-bug-fix-tracing.zh_CN.md b/proposal/A1-bug-fix-tracing.zh_CN.md new file mode 100644 index 0000000..a0ec30d --- /dev/null +++ b/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 记录可能无法解析，需要解析工具做兼容。