学会提问,玩转 GitHub 的问题单(issue)

简介:

对于大多数开源项目来讲,问题追踪系统Issue-tracking system是至关重要的。虽然有非常多的开源工具提供了这样的功能,但是大量项目还是选择了 GitHub 自带的问题追踪器Issue Tracker。

它结构简单,可以让其他人可以非常轻松地参与进来,但这才仅仅是开始。

如果没有适当的处理,你的储存库repository会变得很庞大,挤满重复的问题单、模糊不明的特性需求单、含混的 bug 报告单。项目维护者会被大量工作压得喘不过气来,新的贡献者也搞不清楚项目当前的工作重点是什么。

接下来,我们一起研究下,如何玩转 GitHub 的问题单。

问题单就是用户的故事

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

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

统一的问题单模板可以大大减轻项目维护者的负担,尤其是开源项目的维护者。我们发现,让用户讲故事的方法总是可以把问题描述的非常清楚。用户讲故事时需要说明“是谁,做了什么,为什么而做”,也就是:我是【何种用户】,为了【达到何种目的】,我要【做何种操作】。

实际操作起来,大概是这样的:

我是一名顾客,我想购买东西,所以我想创建个账户。

我们建议,问题单的标题始终使用这样的用户故事形式。你可以设置问题单模板来保证一致性。

image

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

这个做法的核心点在于,问题单要清晰的呈现给它涉及的每一个人:它要尽量简单的指明受众(或者说用户),操作(或者说任务),和输出(或者说目标)。不过,不需要过分拘泥于这个模板,只要能把故事里的是什么事情或者是什么原因说清楚,就达到目的了。

高质量的问题单

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

好的问题单尽量满足如下条件:

客户价值所在

避免使用术语或晦涩的文字,就算不是专家也能看懂

可以切分,也就是说我们可以逐步解决问题

尽量跟其他问题单没有瓜葛,依赖其它问题会降低处理的灵活性

可以协商,也就说我们有好几种办法达到目标

问题足够小,可以非常容易的评估出所需时间和资源

可衡量,我们可以对结果进行测试

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

如果一个问题单很难衡量,或者很难在短时间内完成,你也一样有办法搞定它。有些人把这种办法叫做“约束”(constraints)。

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

问题单里面有什么?

敏捷方法中,用户故事里通常要包含验收指标或者标准。在 GitHub 里,建议大家使用 markdown 格式的清单来概括解决这个问题单需要完成的任务。优先级越高的问题单应当包含更多的细节。

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

image

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

在必要的情况下,你还可以链接到其他问题单,以进一步明确任务。(GitHub 里做这个挺方便的)

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

以问题单的形式收到到问题所在后,还可以用 API 更深入的了解软件的健康度。

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

有些问题单管理工具提供的 API 可以提高额外信息,比如预估时间或者历史进度。

团队协同一致

团队决定使用某种问题单模板后,如何让所有人都照做?存储库里的 ReadMe.md 其实也可以是你们项目的 “How-to” 文档。这个文档应描述清楚这个项目是做什么的(最好是用可以搜索的语言),以及其他贡献者应当如何参与进来(比如提交需求单、bug 报告、建议,或者直接贡献代码)。

image

在 ReadMe 文件里增加清晰的说明,供新协作者参考

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

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

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

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

文章转载自 开源中国社区 [http://www.oschina.net]

目录
相关文章
|
前端开发 JavaScript 程序员
用GitHub Issue取代多说,是不是很厉害?
摘要: 别了,多说,拥抱Gitment。 2017年6月1日,多说正式下线,这多少让人感觉有些遗憾。在比较了多个博客评论系统,我最终选择了Gitment作为本站的博客评论系统: UI简洁,适合我的博客风格 使用GitHub账号登陆,适合技术博客 使用GitHub Issues写评论,符合程序员的习惯 1. 注册OAuth Application 因为Gitment使用了GitHub的服务,因此需要注册OAuth application。
904 0
|
20天前
|
开发工具 git C++
【够用就好002】外行第一次发布github项目仓库
#deepseek#自学 记录外行学习代码的历程 今天是上传自己的工具代码到github仓库,一直以来是伸手党克隆别人的项目,今天在deepseek的辅导下上传自己的内容。
|
2月前
|
开发工具 git
如何操作github,gitee,gitcode三个git平台建立镜像仓库机制,这样便于维护项目只需要维护一个平台仓库地址的即可-优雅草央千澈
如何操作github,gitee,gitcode三个git平台建立镜像仓库机制,这样便于维护项目只需要维护一个平台仓库地址的即可-优雅草央千澈
210 69
如何操作github,gitee,gitcode三个git平台建立镜像仓库机制,这样便于维护项目只需要维护一个平台仓库地址的即可-优雅草央千澈
|
5月前
|
编解码 Oracle Java
java9到java17的新特性学习--github新项目
本文宣布了一个名为"JavaLearnNote"的新GitHub项目,该项目旨在帮助Java开发者深入理解和掌握从Java 9到Java 17的每个版本的关键新特性,并通过实战演示、社区支持和持续更新来促进学习。
149 3
|
7月前
|
存储 安全 Java
【事故】记一次意外把公司项目放到GitHub并被fork,如何使用DMCA下架政策保障隐私
在一次意外中,作者因三年前将测试代码遗忘在GitHub上而遭遇了代码被他人fork的问题。为解决这一危机,作者详细介绍了如何通过GitHub的DMCA下架通知流程安全删除敏感代码,包括处理私人信息和商标侵权的具体步骤。本文不仅提供了实用的操作指南,还强调了及时响应的重要性,帮助读者避免类似风险
172 1
【事故】记一次意外把公司项目放到GitHub并被fork,如何使用DMCA下架政策保障隐私
|
7月前
|
人工智能 Rust JavaScript
Github 2024-08-26 开源项目周报Top15
根据Github Trendings的统计,本周共有15个项目上榜。以下是按开发语言汇总的项目数量:Python项目8个,TypeScript、C++ 和 Rust 项目各2个,Jupyter Notebook、Shell、Swift 和 Dart 项目各1个。其中,RustDesk 是一款用 Rust 编写的开源远程桌面软件,可作为 TeamViewer 的替代品;Whisper 是一个通用的语音识别模型,基于大规模音频数据集训练而成;初学者的生成式人工智能(第2版)则是由微软提供的18门课程,教授构建生成式AI应用所需的知识。
200 1
|
7月前
|
Rust Dart 前端开发
Github 2024-08-19 开源项目周报Top15
根据Github Trendings的统计,本周(2024年8月19日统计)共有15个项目上榜。按开发语言分类,上榜项目数量如下:Python项目最多,有7项;其次是JavaScript和TypeScript,各有3项;Dart有2项;HTML、PowerShell、Clojure和C++各1项。此外,还介绍了多个热门项目,包括Bootstrap 5、RustDesk、ComfyUI、易采集、Penpot等,涵盖了Web开发、远程桌面、自动化测试、设计工具等多个领域。
164 1
|
7月前
|
JavaScript 前端开发 Go
Github 2024-08-12 开源项目周报 Top14
本周Github Trendings共有14个项目上榜,按开发语言汇总如下:Python项目7个,TypeScript项目5个,C项目2个,JavaScript项目2个,Go和Batchfile项目各1个。其中亮点包括开发者职业成长指南、Windows激活工具、ComfyUI图形界面、AFFiNE知识库、易采集可视化爬虫等项目,涵盖多种实用工具和开源平台。
285 1
|
7月前
|
SQL JavaScript 前端开发
Github 2024-08-05 开源项目周报 Top15
根据 Github Trendings 的统计,本周(2024年8月5日统计)共有15个项目上榜。以下是根据开发语言汇总的项目数量: - Go 项目:4个 - JavaScript 项目:3个 - Python 项目:3个 - Java 项目:2个 - TypeScript 项目:2个 - C 项目:1个 - Shell 项目:1个 - Dockerfile 项目:1个 - 非开发语言项目:1个
249 2
|
7月前
|
存储 JavaScript 前端开发
Github 2024-07-29 开源项目周报Top15
根据 Github Trendings 的统计,本周(2024年7月29日统计)共有15个项目上榜。按开发语言分类,项目数量如下:Python、Java、HTML 和 C 项目各有2项;TypeScript、JavaScript、Vue 和 Go 各有1项;另有1项非特定语言项目、1项 Dart 项目、1项 C++ 项目、1项 Rust 项目及1项 Jupyter Notebook 项目。这些项目涵盖了多种领域,如API开发、照片管理、PDF处理、AI技术等。
119 1

热门文章

最新文章