超简单玩转 GitHub 的问题单（issue）

问题单就是用户的故事

个人团队曾经和开源专家 Jono Bacon作过一次对话，他是《社区艺术》一书的做者、一位战略顾问、前 GitHub 社区总监。他告诉咱们，高质量的问题单是项目成功的关键。有些人把问题单仅仅看做是一堆你不得不去处理的问题列表，可是若是这些问题单管理完善，进行了分类并打上标签，会使人意想不到的提高咱们对代码和社区的了解程度，也让咱们更清楚问题的关键点在哪里。

“在提交问题单时，用户不太会有耐心或者有兴趣把问题的细节描述清楚。在这种状况下，你应当努力花最短的时间，尽可能多的获取有用的信息。”，Jono Bacon 说。

统一的问题单模板能够大大减轻项目维护者的负担，尤为是开源项目的维护者。咱们发现，让用户讲故事的方法老是能够把问题描述的很是清楚。用户讲故事时须要说明“是谁，作了什么，为何而作”，也就是：我是【何种用户】，为了【达到何种目的】，我要【作何种操做】。

实际操做起来，大概是这样的：

我是一名“顾客”，我想“购买东西”，因此我想“建立个帐户”。

咱们建议，问题单的标题始终使用这样的用户故事形式。你能够设置问题单模板来保证一致性。

问题单模板让特性需求单保持统一的形式

这个作法的核心点在于，问题单要清晰的呈现给它涉及的每个人：它要尽可能简单的指明受众（或者说用户），操做（或者说任务），和输出（或者说目标）。不过，不须要过度拘泥于这个模板，只要能把故事里的是什么事情或者是什么缘由说清楚，就达到目的了。

高质量的问题单

问题单的质量是良莠不齐的，这一点任何一个开源软件的贡献者或维护者都能证明。在《The Agile Samurai》中概述过一个良好的问题单所应具有的素质。

好的问题单尽可能知足以下条件：

• 客户价值所在
• 避免使用术语或晦涩的文字，就算不是专家也能看懂
• 能够切分，也就是说咱们能够逐步解决问题
• 尽可能跟其余问题单没有瓜葛，依赖其它问题会下降处理的灵活性
• 能够协商，也就说咱们有好几种办法达到目标
• 问题足够小，能够很是容易的评估出所需时间和资源
• 可衡量，咱们能够对结果进行测试

不知足上述条件的问题单呢? 要有约束

若是一个问题单很难衡量，或者很难在短期内完成，你也同样有办法搞定它。有些人把这种办法叫作“约束”（constraints）。

例如，“这个产品要快”，这种问题单不符合故事模板，并且是没办法协商的。多快才是快呢？这种模糊的需求没有达到“好问题单”的标准，可是若是你进一步定义一下，例如“每一个页面都须要在 0.5 秒内加载完”，那咱们就能更轻松地解决它了。咱们能够把“约束”看做是成功的标尺，或者要实现的里程碑。每一个团队都应该按期的对“约束”进行测试。

问题单里面有什么？

敏捷方法中，用户故事里一般要包含验收指标或者标准。在 GitHub 里，建议你们使用 markdown 格式的清单来归纳解决这个问题单须要完成的任务。优先级越高的问题单应当包含更多的细节。

好比说，你打算提交一个关于新版网站主页的问题单。那这个问题单的子任务列表可能就是这样的：

使用 markdown 的清单把复杂问题拆分红多个部分

在必要的状况下，你还能够连接到其余问题单，以进一步明确任务。（GitHub 里作这个挺方便的）

将特性定义的越细化，越容易跟踪进度、测试，最终能更高效的发布有价值的代码。

以问题单的形式收到到问题所在后，还能够用 API 更深刻的了解软件的健康度。

“在统计问题单的类型和趋势时，GitHub API 能够发挥巨大做用”，Bacon 告诉咱们，“若是再作些数据挖掘工做，你就能发现代码里的问题点、社区里的活跃成员，或者其余有用的信息。”

有些问题单管理工具提供的 API 能够提升额外信息，好比预估时间或者历史进度。

团队协同一致

团队决定使用某种问题单模板后，如何让全部人都照作？存储库里的 ReadMe.md 其实也能够是大家项目的 “How-to” 文档。这个文档应描述清楚这个项目是作什么的（最好是用能够搜索的语言），以及其余贡献者应当如何参与进来（好比提交需求单、bug 报告、建议，或者直接贡献代码）。

在 ReadMe 文件里增长清晰的说明，供新协做者参考

ReadMe 文件是提供“问题单指引”的完美场所。若是但愿特性需求单遵循“用户讲故事”的格式，那就把格式写在 ReadMe 里。若是使用某种跟踪工具来管理待办事项，那就标记在 ReadMe 里，这样别人也能看到。

“问题单模板、合理的标签、提交问题单的指导文档、确保问题单被分类并及时回应，这些对于开源项目都相当重要”，Bacon 说。

记住一点：这不是为了完成工做而作的工做。这是让其余人更轻松的发现、了解、融入你的社区而设立的规则。

"关注社区的成长，不只要关注参与开发者的的数量增加，也要关注那些在问题单上帮助咱们的人，他们让问题单更加明确、保持更新，这是活跃沟通和高效解决问题的力量源泉"，Bacon 说。

原文来自：https://linux.cn/article-8002-1.html

本文地址：http://www.linuxprobe.com/play-github-issue.html