【必读】如何正确的提出一个 Issue

[Ligoml]

什么是 Issue ？

Issue，GitHub 官方译为议题，使用 GitHub Issues 可以用来追踪在 GitHub 上的想法、反馈、任务或缺陷。更多信息可参考GitHub Issues 官方文档。

常见的几种 Issue 使用场景有：

• 报告一个框架bug
• 提交一项功能建议
• 记录一个待完成任务
• 指出文档缺失/安装问题
• 答疑交流

如何提 Issue ？

PaddlePaddle 有很多代码仓库，为了使你的 Issue 能够获得快速响应与解决，我们建议你初步判断下 Issue 所属仓库，并在对应仓库下提 Issue。PaddlePaddle 目前活跃维护的仓库有：Paddle、Paddle-Lite、Serving、Paddle.js、PaddleSlim、PaddleNLP、PaddleOCR、PaddleClas、PaddleDetection、PaddleSeg、PaddleGAN、PaddleVideo、PaddleSpeech、PaddleRec、PARL、PaddleScience、PaddleHub、PaddleX、VisualDL、Paddle2ONNX、X2Paddle。

我们以飞桨框架 Paddle 仓库下提 Issue 为例，点击 New issue 按钮后，你需要选择一个模板来提交 Issue：

点击模板对应的 Get Started 按钮，则会为你创建对应的模板。

此外，飞桨团队十分鼓励社区开发者参与共建，主要形式有以下两种：

• 文档错别字修改，小的 Bug fix：我们非常欢迎你主动参与飞桨框架建设，在提 Issue 时一并 提 PR 修复 Bug/文档。
• 发布的外部贡献任务（）：这些是我们收集整理的，需求相对明确和独立，且适合直接上手的需求，我们非常欢迎你认领自己感兴趣的任务，提 PR 实现新需求。

下文会详细介绍各个模板的使用方式：

🐛 报 BUG Bug Report

发现一个 Bug 意味着飞桨框架又将减少一个缺陷，我们十分欢迎你向我们报告 Bug。为了减少沟通成本，尽快定位问题，我们希望你可以提供：Bug 复现环境、Bug 复现步骤及最小代码集，以便我们可以通过运行代码来重现错误。

尤其是最小代码集，当你在准备代码的时候，你其实已经可以大体分辨该问题是「使用错误」还是「系统 Bug」，这是一种非常高效的排查问题方式。

• 如果定位到「使用错误」，不是 Bug，请同步解决方案并及时关闭 Issue，方便后来人。
• 如果发现是小问题（文档错别字修改，小的 Bug fix），我们非常欢迎你直接参与飞桨框架建设，提 PR 修复 Bug。
• 如果无法自行定位 Bug，你需要上传最小可复现代码到 AIStudio 或 GitHub gist ，我们会快速跟进并及时向你同步进展。

注：提一个信息完整、内容清晰的 Issue 不仅有利于自己梳理问题，也方便社区其他开发者和飞桨研发团队快速响应，共同解决问题。

🚀 新需求 Feature Request

如果你在使用飞桨的过程中发现自己的需求没有被满足，如功能或模型缺失、功能不全或无法使用、精度/性能不符合预期等问题，你可以向我们提交新需求。请尽可能包含需求场景、功能描述、使用频次等信息，全面的信息有利于我们准确评估你的需求。

我们会通过 label 的方式反馈需求评审进度及结果，包含：（需求调研中）、（需求review中）、（需求开发中）、（需求开发完毕）。

如果经过飞桨团队评估，需求相对明确和独立，且适合直接上手，我们会将该需求以外部贡献任务的形式发布出来，并打上的标签，非常欢迎你提 PR 实现新需求。

🗂 安装 Build/Installation Issue

安装&编译 Paddle 请优先参考 官网文档，若未能解决你的问题，你可以通过 Issue 来反馈。我们希望你可以提供完整的问题描述和版本&环境信息，方便我们复现你的问题并及时解决。

📚 文档 Documentation Issue

飞桨团队对文档十分重视，没有什么问题是一份好文档解决不了的。如果你在阅读飞桨官方文档时发现问题，包括但不限于：描述引发误解、内容不全、内容有误等，欢迎你通过 Issue 向我们反馈。

待研发同学确认后，我们非常欢迎你向 Paddle&docs 提交 PR 修复文档。

🙋🏼‍♀️🙋🏻‍♂️提问 Ask a Question

一般来说，更推荐使用 AIStudio论坛 自助交流的方式，你可以在论坛畅所欲言，找寻志同道合的小伙伴。

飞桨研发团队更希望将精力放在解答疑难问题、处理 Bug 和承接需求上，如果你的问题没有在论坛获得解答，你可以通过提 Issue 的方式与我们交流。

🧩 其他 Others

如果你的问题无法使用上述模板，包括但不限于：优化性建议、框架使用体验反馈、版本兼容性问题、报错信息不清楚、对飞桨团队的建议（如 Issue 处理流程建议）等。你可以在这里提 Issue，这是一个完全空白的输入框，你可以按照自己的意愿填写内容。

写在最后

非常感谢你参与飞桨开源社区，你可以从提一个 Issue 开始，

• 提 PR 完善飞桨框架，成为我们的 Contributor；
• 参加 working group，承担飞桨例行工作（如 docs review）；
• 参加社区生态活动，如黑客松、论文复现，与飞桨共同成长；
• 更多玩法等你解锁🔓

让我们共同打造更好用的深度学习框架🎉！