技术英语 / 系统课时

描述 Issue 的复现过程

描述 Issue 的复现过程

Issue 的价值在于让另一个人能够看到同一个问题。复现信息写得越具体,维护者越少需要来回追问。本篇把环境、操作步骤、实际结果和预期结果拆开组织,并用英文写出一条可以直接进入排查流程的最小复现路径。

学习目标

  • 只记录与故障相关的环境信息,避免无效信息堆积
  • 把复现步骤写成可重复、可观察的动作序列
  • 清楚区分 actual result、expected result 和补充诊断信息

先固定复现环境

环境信息的目标不是列出整台机器的配置,而是帮助维护者判断差异来源。通常优先记录应用版本、操作系统、运行时或浏览器版本,以及与问题直接相关的配置。

如果问题只在特定版本出现,应使用精确值,例如 App 3.8.1,不要写 latest version。latest 会随时间变化,几周后再阅读 Issue 时已经失去可复现性。涉及配置时,只摘录影响当前行为的字段,并删除密码、Token、内部地址等敏感内容。

对于偶发问题,还应补充发生频率,例如 Reproduces about 3 out of 10 attempts.。这能避免维护者因为第一次没有触发就错误地判断问题不存在。

把步骤写成最短可重复路径

复现步骤应从一个明确的初始状态开始,每一步只描述一个可执行动作。避免 Configure it normally、Do the usual setup 这类依赖个人经验的表达,也不要把原因推测写进操作步骤。

好的步骤通常可以让维护者逐项执行并确认当前状态。如果某一步不是必需的,就从最小复现中删除;步骤越短,越容易隔离真正的触发条件。

下面是一份片段示例,展示环境、步骤和结果的基本组织方式:

markdown
## Environment
- App: 3.8.1
- OS: Ubuntu 24.04
- Browser: Chrome 153

## Steps to reproduce
1. Start the application with the default configuration.
2. Open Settings > Network.
3. Set the proxy URL to an unreachable address.
4. Click Save.

## Actual result
The Save button remains disabled after the connection check fails.

## Expected result
The Save button becomes available again so the proxy setting can be corrected.

预期结果:维护者可以在相同版本和初始条件下逐步执行操作,并明确知道最后应比较哪个可见行为,而不需要先询问“具体怎么触发”或“你原本期望什么”。

分开写实际结果和预期结果

Actual result 只记录真实观察,例如错误消息、状态码、页面行为或崩溃位置;Expected result 描述按照文档、既有行为或产品规则本应发生什么。两者越接近可观察事实,越容易验证修复是否有效。

不要写 It does not work as expected.,因为它既没有说明“实际发生什么”,也没有定义“expected”。更好的形式是 The request returns 500 instead of 404 when the resource does not exist.,维护者可以直接针对返回行为建立测试。

如果你对根因只有猜测,可单独写成补充信息,并使用 I suspect、This may be related to 等表达降低确定性。不要把推测伪装成已经确认的事实。

只附上能推进排查的证据

日志、截图和最小示例的作用是补足无法从步骤直接观察的信息。错误日志应保留关键上下文和时间点,但不要一次粘贴完整启动日志;截图适合界面错位等视觉问题,却不能替代文本中的操作路径和错误消息。

提交前可以让另一位读者只按照 Issue 内容尝试一次:如果他能够确定环境、完成每一步,并判断实际结果是否偏离预期,这份复现说明就已经具备进入定位和修复流程所需的核心信息。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

描述 Issue 的复现过程

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通