技术英语 / 系统课时
发起信息完整的 GitHub Issue
发起信息完整的 GitHub Issue
高质量 Issue 的目标不是“把问题说出来”,而是让维护者在第一次阅读后就能判断问题类型、复现条件和下一步动作。本篇将用英文模板组织 Bug、功能请求和使用问题,并减少反复追问。
学习目标
- 区分 Bug、功能请求和使用问题应提供的信息
- 用简洁英文写清环境、复现步骤、期望结果与实际结果
- 在提交前依据项目模板和贡献规范做自检
先判断自己在提交什么
同样是“有问题”,Issue 类型不同,维护者需要的信息也不同。Bug 需要可复现证据;功能请求需要说明需求和价值;使用问题则应先交代目标、当前做法和卡点。
| 类型 | 最重要的信息 | 常见缺陷 |
|---|---|---|
| Bug | 环境、复现步骤、实际结果、期望结果 | 只有一句“doesn't work” |
| Feature request | 使用场景、现有限制、期望能力 | 只写“please add X” |
| Usage question | 目标、尝试过的方法、报错或结果 | 没说明真正想完成什么 |
提交前先查看仓库的 Issue template、CONTRIBUTING.md 和支持渠道。有些项目会把普通使用问题引导到 Discussions、论坛或社区群组;尊重这些约定,比套用一个“万能 Issue 模板”更重要。
把 Bug 写成可复现的问题
Bug 标题应描述“什么条件下出现什么异常”,而不是表达情绪。例如 Crash when parsing an empty config file 比 Parser is broken 更便于搜索和归类。
片段示例:下面是可直接改写的 Issue 正文结构,它不是可执行代码,具体环境值和复现步骤应替换成当前项目的真实信息。
### Context
I am using the CLI to validate generated configuration files.
### Environment
- OS: <OS>
- Tool version: <VERSION>
- Runtime: <RUNTIME_VERSION>
### Steps to reproduce
1. Create an empty configuration file.
2. Run the validator against that file.
3. Observe the process exit unexpectedly.
### Expected behavior
The validator should report that the file is empty and exit with a non-zero status.
### Actual behavior
The process terminates before printing a validation message.
### What I tried
I reproduced the issue with a clean configuration and without custom plugins.这里最关键的是把 Expected behavior 和 Actual behavior 分开。It should work 信息量太低;更好的写法是明确应该看到的状态、消息或返回结果。复现步骤也要从“最小可行条件”开始,避免一次塞入完整业务流程。
环境信息应尽量来自命令,而不是凭记忆填写。例如确认 Git 版本:
git --version预期输出
git version <VERSION>实际 <VERSION> 会随本机安装版本变化。类似地,项目若依赖特定运行时、数据库或浏览器,也应记录能够影响复现结果的版本。
功能请求先解释问题,再提出方案
功能请求不是设计命令。维护者首先需要知道“为什么现有行为不够用”,其次才是你希望新增什么。一个更容易评估的结构是:use case → current limitation → proposed behavior → alternatives。
例如不要只写 Please add CSV export.,而可以写:We need to export audit results into an internal reporting pipeline. The current JSON output requires an extra conversion step. Would you consider adding a CSV output mode?
如果你已经考虑过替代方案,也应明确写出:I considered converting the JSON output in a separate script, but that duplicates field mapping in several repositories. 这能帮助维护者判断需求是否值得进入项目本身。
使用问题要交代目标和已尝试方案
提问时,How do I configure this? 往往过于宽泛。更有效的表达是先说明目标,再展示当前做法和结果,例如:I am trying to run the formatter only on changed files in CI. I tried passing the file list from git diff, but the command treats it as one argument.
“已尝试方案”不是为了证明你很努力,而是排除已经验证过的方向。可以使用 I tried ...、I also checked ...、This works when ..., but fails when ... 这些句式,让维护者快速定位边界。
提交前做一次维护者视角检查
提交前检查三个问题:维护者能否在不了解你的业务背景时理解问题;能否按步骤得到同样结果;能否知道你已经排除了哪些常见原因。必要时附最小仓库、日志片段或截图,但不要上传密钥、Token、私有地址或客户数据。
语气保持中性即可。I may be missing something, but... 适合表达不确定性;Could you confirm whether this is expected? 适合行为边界不明确的情况。避免 obviously、simply、you should 这类容易让协作变得对抗的措辞。一个信息完整、范围清楚的 Issue,本质上是在替维护者减少诊断成本。