proposal: add bug fix tracing strategy for version releasing #26
Conversation
|
CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅ |
|
I have read the CLA Document and I hereby sign the CLA |
proposal/A1-bug-fix-tracing.zh_CN.md
Outdated
| tRPC 当前的 ChangeLog 会提示每个版本新增的 Features 以及修复的 Bugs，但是未提供 Bug 跟踪信息。 | ||
| 即，用户在选择 tRPC 版本时，可以得知所选版本已经解决了那些 Bugs，但是无法得知还有那些 Bugs 未解决。 | ||
|
|
||
| 期望借助某些工具可以达到这样的目标：用户选择 tRPC 的某个具体版本后，提示当前版本有那些 Bugs 已经被修复，那些 Bugs 还未修复。 |
There was a problem hiding this comment.
用户可以在tRPC官网上通过选择tRPC的某个具体版本后，除了看到这个版本修复了哪些Bugs，还可以看到这个版本存在哪些 Bugs。
There was a problem hiding this comment.
期望借助某些工具 -》 目标：定义框架发布版本时changelog中bugfix的规范格式，然后通过自动化的工具提取数据后，用户可以在tRPC官网上通过选择tRPC的某个具体版本后，除了看到这个版本修复了哪些Bugs，还可以看到这个版本存在哪些 Bugs。
proposal/A1-bug-fix-tracing.zh_CN.md
Outdated
|
|
||
| 期望借助某些工具可以达到这样的目标：用户选择 tRPC 的某个具体版本后，提示当前版本有那些 Bugs 已经被修复，那些 Bugs 还未修复。 | ||
|
|
||
| 例如：选择 `trpc-cpp/v0.4.2`，提示如下内容： |
proposal/A1-bug-fix-tracing.zh_CN.md
Outdated
| ## 背景 | ||
|
|
||
| tRPC 当前的 ChangeLog 会提示每个版本新增的 Features 以及修复的 Bugs，但是未提供 Bug 跟踪信息。 | ||
| 即，用户在选择 tRPC 版本时，可以得知所选版本已经解决了那些 Bugs，但是无法得知还有那些 Bugs 未解决。 |
proposal/A1-bug-fix-tracing.zh_CN.md
Outdated
|
|
||
| ### 如何跟踪 Bug 信息 | ||
|
|
||
| 所有的 Bugs 均通过 Issues 来跟踪。提交 Issue 时，需要按照模版规范提交。 |
There was a problem hiding this comment.
issue 的提交格式确实很难遵循，但是可以提供一个 issue template，以规范用户。这个是 trpc-go issue 的提交模版，用户只能从中选择： https://github.com/trpc-group/trpc-go/issues/new/choose
There was a problem hiding this comment.
这边想进一步确定下：
- go 这边会采用 issue template，cpp 是否采用 issue template ？
- issue template 里面的 bug template 是否需要对齐？
There was a problem hiding this comment.
问题-1： Issue template 是一个好方式，cpp 会采用 issue temaplate。
问题-2: Issue template 内容大体一致，可能不需要完全一致，这块不要严格对齐。
按照设想，是期望直接通过 ChangeLog 维护的 Bug 修复记录来生成确定版本中的 Bug 修复统计数据。
Issue 用作未关闭 Bug 信息来源。
proposal/A1-bug-fix-tracing.zh_CN.md
Outdated
|
|
||
| ## [v0.3.1](https://github.com/xx/yy)(2023-10-19) | ||
| ... | ||
| ### Bug Fixes and Other Changes |
There was a problem hiding this comment.
Bug Fixes and Other Changes -》Bug Fixes即可
liucf3995
force-pushed
the
feature/lioncfliu_A1_bug_fix_tracing_with_issues_and_changelog
branch
2 times, most recently
from
3a83c6a
to
a97aad2
Compare
proposal/A1-bug-fix-tracing.zh_CN.md
Outdated
| 主要借助 Issue 和 ChangeLog 两部分信息记录 Bug 修复信息。 | ||
|
|
||
| * 所有的 Bug 信息通过 Issue 来跟踪，通过 Issue 关闭和打开的状态区分未修复 Bug 清单（未关闭的 Bug Issue）。 | ||
| * ChangeLog 记录 Bug 引入版本号、修复版本号（一般是当前版本号）、关联的 #PR。同时，也记录未修复 Bug 的 #Issue 和引入版本号。 |
There was a problem hiding this comment.
ChangeLog 还会记录未修复的 bugs 吗？
- 它会和 Issue 重复
- ChangeLog 只有在发版时才会改。未修复的 Bug 只能到当时发版时间，还没来得急修复的 Bug。无法时实反应最新 Bug。
- 查看旧版本 ChageLog 时，看到前面第一段写的未修复 Bug（实际可能已经在新版本修复了），对用户来说，感受可能不会很好，而且可能引起误解，以为这个 Bug 现在还存在。甚至这个不是 bug，当时误以为是 bug 写进 ChangeLog 里面了。
There was a problem hiding this comment.
按照设想，是期望直接通过 ChangeLog 维护的 Bug 修复记录来生成确定版本中的 Bug 修复统计数据，而不想过多依赖使用者输入的 Issue 信息（工具需要解析 Issue 内容），维护 Issue 信息准确可能也是一件不容的事情的，不如直接维护可控的 ChangeLog。
关于提到的问题：
- 它和 Issue 重复。 Issue 的转台会被关闭，或者打开。但是 ChangeLog 是一个快照信息，记录了 Issue 在每个具体版本解决或者未解决状态。
- 关于时效问题，确实存在。那这里的想法时：遇到紧急、严重的 Bug 也应及时发布补丁来修复，这样， Bug 会及时同步并修复；如果不紧急，那可能影响是可控的，tRPC 页面可以做些额外的提示，提示最新版本~Master 之间新提交的 Bug 修复情况。
- 关于重复、误解问题。这块没有想好的解决办法，可能较好的做法是：及时修复发现的 Bug，不让它横跨多个版本还没有修复。
There was a problem hiding this comment.
为了运维简单，选 change log 作为唯一 bug 数据源也能接受吧
|
|
||
| * v1.2.0：由 v1.2.0 引入。 | ||
| * v1.1.0~：1.1.0 ~ 修复版本之间的某个引入，具体版本号未知。 | ||
| * ~v2.2.0：起始版本 ~ v1.2.0 之间某个版本引入，具体版本号未知。 |
There was a problem hiding this comment.
* v1.2.0~v1.4.0：由 v1.2.0 引入，在 v1.4.0 修复。
* v1.2.0~：由 v1.2.0 引入，待修复。
* ~v1.4.0：引入版本未知，在 v1.4.0 修复。
* ~v1.3.0~：引入版本未知，确定可以在 v1.3.0 复现，待修复。
|
|
||
| ### Bug Fixes | ||
| Closed Bugs: | ||
| - **$scope:** $prompt (!#PR) ($version) |
There was a problem hiding this comment.
用于 bug tracker 解析的信息应该尽可能地不要影响 Change Log 的阅读。
建议把相关信息放在每个 bug 的最后一行
### Bug Fixes
- bug description
[$scope] [#PR] [version]
- ...
proposal/A1-bug-fix-tracing.zh_CN.md
Outdated
| - **$scope:** $prompt (!#PR) (~$version) | ||
| - **$scope:** $prompt (!#PR) ($version~) | ||
|
|
||
| Open Bugs: |
There was a problem hiding this comment.
当后续发现新 bug 时，每个存在这个 bug 的历史版本的 Open Bugs 都得跟着一起更新？
这样会不会太重了？
There was a problem hiding this comment.
历史已经发布的版本中 Open Bugs 不做更新。在提示具体版本 Bug 的时候，做版本范围覆盖计算时过滤一下应该可以满足信息展示需求的。
| Bug-04(#4): xx。从 v1.1.1 引入。 | ||
| ``` | ||
|
|
||
| ## 业界实现 |
There was a problem hiding this comment.
我感觉得写一个小服务，去 watch issue, tags 的变更，并把所有 bug 数据更新到 DB 中。官网查看一个版本时，从数据库里 select 出影响范围覆盖该版本的 bugs。
如果只依赖 change log，change log 的维护成本感觉会很高。
There was a problem hiding this comment.
你提到的方法也非常不错。
关于 Bug 统计逻辑：
解析 ChangeLog 后，可以获取所有 Bug 对应的引入版本号、修复版本号（如果有的话）、#Issue 或者 #PR，这样可以计算出 Bug 涉及的代码版本。
liucf3995
force-pushed
the
feature/lioncfliu_A1_bug_fix_tracing_with_issues_and_changelog
branch
2 times, most recently
from
6484a2a
to
d3a223b
Compare
liucf3995
force-pushed
the
feature/lioncfliu_A1_bug_fix_tracing_with_issues_and_changelog
branch
from
d3a223b
to
38aa257
Compare
No description provided.