GitHub 提问 (Issue) 高质量操作指南

[justlovemaki]

GitHub 提问 (Issue) 高质量操作指南

一、 提问前的准备：不要做“伸手党”

在点击 New Issue 按钮之前，请务必完成以下步骤。这不仅是对维护者的尊重，也是向黑客文化致敬。

1. 自我排查 (RTFM & STFW)

   • 查阅文档 (Read The Fucking Manual): 确保你的问题不是文档中已经写明的操作步骤。
   • 搜索网络 (Search The Fucking Web): 使用 Google 搜索错误代码或现象。
   • 搜索旧 Issues: 在该仓库的 Issues 栏（包括 Closed 的）搜索关键词，很大概率有人遇到过相同问题。
   • 自我尝试: 尝试阅读源码，或自己通过简单的调试（Debug）来定位问题。

2. 明确这是 Bug 还是咨询

   • 如果你不确定这是软件的缺陷，请不要在标题中轻易使用“Bug”这个词。
   • 如果是询问用法（如“Java怎么学”），请确保你提供了足够的背景信息（参考下文）。

---

二、 撰写 Issue：从模糊走向精确

1. 标题 (Title)

标题是决定开发者是否点击进来看的第一要素。

• ❌ 糟糕的标题：
  • “救命啊！程序崩了！”
  • “有个 Bug，急急急！”
  • “为什么用不了？”
• ✅ 优秀的标题（对象 + 偏差）：
  • 格式： [模块/版本] 在特定环境下出现预期外的行为
  • 示例： “X.org 6.8.1 鼠标指针在 MV1005 芯片组下显示变形”
  • 示例： “Spring Boot 2.5: 无法在 Docker 容器中正确加载配置文件”

2. 内容主体 (Description)

一个高质量的 Issue 应该包含以下三个核心维度：背景、目标、限制条件/复现步骤。

A. 如果是咨询类问题（How-to）

不要问“某某好用吗？”或“怎么做？”，需提供：

• 背景 (Identity/Context): 你的身份、当前技术水平、已掌握的知识。
• 目标 (Goal): 你最终想实现什么效果（而不是你现在卡在哪个中间步骤）。
• 限制 (Constraints): 预算、时间、硬件环境、网络环境。

示例：
“本人是大三学生（背景），需要完成期末项目，要在 500元/月 预算内选择一个适合国内访问的云服务器（限制），用于部署一个轻量级 Java Web 应用（目标），请问有推荐的方案吗？”

B. 如果是技术故障类问题（Bug Report）

请务必包含以下结构化信息：

• 环境信息 (Environment):
  • 操作系统及版本（如 Windows 10 21H2, Ubuntu 20.04）
  • 软件/库的版本（如 Python 3.9, React 17.0.2）
  • 硬件配置（如果相关，如显卡型号、内存大小）
• 复现步骤 (Steps to Reproduce):
  • 按时间顺序列出导致问题的操作步骤。
  • 如果是代码问题，必须提供“最小可复现代码” (Minimal Reproducible Example)。不要贴几百行无关代码，只贴能复现问题的最简片段。
• 现象描述 (Symptoms, not Guesses):
  • 描述你看到了什么（错误日志、界面表现），而不是你猜哪里坏了。
  • 引用日志： 使用 Markdown 的代码块（```）包裹错误日志，不要截图（截图无法被搜索）。
• 你做过的尝试:
  • “我尝试了搜索 Google，找到了方案 A，但在我的环境下无效，报错如下...”

---

三、 沟通礼仪与心态

1. 话不在多而在精

   • 使用清晰、合乎逻辑的语言。
   • 排版整洁，善用 Markdown 格式（代码块、粗体、列表）。
   • 不要使用大量感叹号、表情符号或“火星文”。

2. 避免无意义的废话

   • 不要问“有人能帮我吗？”（直接说事）。
   • 不要标题党写“紧急”（你的问题对开发者来说通常并不紧急）。
   • 不要低声下气（“我是小白，求大神”），也不要傲慢自大（“这也太烂了”）。保持专业、平等的交流态度。

3. 后续跟进

   • 如果解决了： 务必回到 Issue 下方回复解决方案，并关闭 Issue（Close Issue）。这对后来者是巨大的帮助。
   • 如果被要求补充信息： 尽快补充。如果你看不懂开发者的回复，请诚实地说：“我看过文档了，但我不理解 -z 参数的含义，您是指...”

---

四、 通用 Issue 模板

在 GitHub 提 Issue 时，如果仓库没有提供模板，建议使用以下格式：

问题描述 (Problem Description)

我在使用 [版本号] 进行 [操作] 时，发现了预期之外的行为。

环境信息 (Environment)

• OS: [例如：macOS Monterey 12.3]
• Software Version: [例如：v1.2.3]
• Dependencies: [例如：Node.js v16.14.0]

复现步骤 (Steps to Reproduce)

1. 运行命令 ...
2. 点击按钮 ...
3. 观察到错误 ...

预期行为 vs 实际行为 (Expected vs Actual)

• 预期： 应该输出 "Success"
• 实际： 输出了错误代码 500

错误日志/代码片段 (Logs/Code)

Error: Unable to connect to database...

尝试过的解决方案 (Attempts)

• 我查阅了官方文档第3章，但按照步骤操作无效。
• 我尝试搜索了 Issue feat: Add structured output support for OpenAI to Gemini conversion #102，但那个解决方案不适用于我的版本。

---

记住：提问的质量，决定了解决问题的效率。做一个聪明的提问者，社区才会更愿意帮助你。