如何正确的提出一个 Issue - 图1

Issue 的作用

Issue 是一种非常好的可沉淀的交流方式,可跟踪,可复现。

我们使用 GitHub Issue 来与社区交流,它有几种应用场景:

如何正确的提出一个 Issue - 图2 Egg 有很多个仓库,为了跟踪方便,我们采用统一入口方式,仅在主仓库开启 Issue 反馈入口:https://github.com/eggjs/egg/issues

更推荐新手开发者通过:https://issue.eggjs.app/ 来提交 Issue。

答疑交流 Usage

一般来说,更推荐使用 stackoverflowCNode 等社区自助交流方式。

另外,也有社区活跃开发者提供的自助交流群:

基于 Egg 团队跟踪方便的考虑,我们适度接受开发者通过 Issue 的方式来提交使用答疑。
但务必请适度控制问题的范畴,避免打扰,具体答疑的 Issue 提交注意事项和规范,参见下一节。

反馈缺陷 Bug

恭喜,发现一个 Bug 意味着我们的应用又少了一个缺陷,快速 Fix 掉即可。

但为了尽可能的减少沟通成本,高效的解决问题,我们期望你能:

首先要仔细阅读

然后期望你能提供:复现步骤,错误日志以及相关配置,请务必按照 Issue 模板填写相关条目,避免挤药膏似交流。

  1. - **Node Version**:
  2. - **Egg Version**:
  3. - **Plugin Name**:
  4. - **Plugin Version**:
  5. - **Platform**:
  6. - **Mini Showcase Repository**:

尤其是最后一项『最小可复现仓库』,请通过 npx egg-init --type=simple 来初始化并上传到你的 GitHub 仓库。

绝大部分情况下,在这个过程中你就会自己发现问题了,这是一种非常高效的问题定位方式:

  • 如果发现是使用错误,不是 Bug,请及时关闭 issue,并把解决方式同步进来,方便后来人。

  • 如果发现是小问题(文档错别字修改,小的 bug fix),欢迎直接参与进来,直接提 PR 优化。

  • 如果还不能解决,此时直接上传最小可复现仓库到你的 GitHub ,我们会快速跟进。

提交新需求 Feature Request

如果你经常关注我们的 Issue,会发现 Egg 团队日常协作中经常会通过 RFC 的方式,来讨论和实现一个新的特性。

我们称之为:『基于 GitHub 的硬盘式异步协作模式』

通过 issue 发起 RFC 提案 -> 讨论定稿-> 提交 Pull Request -> Code Review -> 发布。

这样便于沉淀,即使是当时没有参与讨论的开发者,事后也能通过 issue 了解某个功能设计的前因后果。

它的模板如下:

  1. ## 背景
  2. - 描述你希望解决的问题的现状
  3. - 附上相关的 issue 地址
  4. ## 思路
  5. 描述大概的解决思路,可以包含 API 设计和伪代码等
  6. ## 跟进
  7. 后续编辑,附上对应的 Pull Request 地址,可以用 `- [ ] some task` 的方式。

其他约束:

  • 标题:[RFC] some title

  • 标签:type: proposals

相关参考:https://github.com/eggjs/egg/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22type%3A+proposals%22