序言
之所以想着翻译这篇文章,是因为我看到国内不管是开源爱好者,还是开发者都不怎么了解 Github Discussions,以致于在 Github 仓库中提问时,总是忘记使用这个好东西,或者问错地方。
引言
GitHub Discussions 可将社区论坛直接带到 GitHub 上的公共或私有仓库中,从而方便与社区交流、提问和回答问题、分享更新等。以下是关于 GitHub Discussions 的必要信息、最佳实践以及其他开源项目是如何使用它的。
文章主要从开源项目维护者角度来说的,主要包括:
- 如何开启 Github Discussions?
- 如何使用 Github Discussions?
- Github Discussions vs Github Issues
Github Discussions 基础篇
GitHub Discussions 专为一起工作的任何开发者社区而设计,它有一个很大的优点:它直接存在于您的版本库中(也就是您已经在工作的地方和您的社区所在的地方),减少了在其他网站上管理第三方论坛时的上下文切换。
它还提供了一个允许开放式对话的异步交流平台,使保存历史信息、常见问题和功能想法变得更加容易。
如何在仓库中开启 Github Discussions?
管理员、维护者或任何有写入权限的人都可以在任何公共或私有版本库中启用 Github Discussions。具体方法如下:
- 打开仓库Setting ,转到Features
- 选中 Discussion 旁边的复选框
- 创建欢迎帖子,开始你的论坛
👇🏻 下面就是这么简单的证据:
使用 GitHub Discussions 的常见用例
Github Discussions 让您能够在 Github 上直接与社区和协作者互动。为了方便用户,它还提供了给讨论打标签、标记有用的答案、投票等功能。
以下是开源社区和团队使用 GitHub Discussions 的一些方法:
-
创建社区公告 :无论您是管理员、维护者还是贡献者,您都可以使用讨论功能发布有关即将发布的版本、路线图决策等的社区公告。nodejs 社区就是这么做的。
-
分享想法并获得社区反馈 :也许您需要有关正在尝试解决的问题的反馈。或者,也许您想分享有关您希望在未来中看到的新功能的想法。Github Discussions 旨在使社区参与变得简单和协作。gatsby 社区就是这么做的 link。
-
讨论新版本 :一些开源社区使用讨论来回答来自更广泛社区的新版本的问题。React 团队就用 Github Discussions 来回答有关其最新版本的问题,并进一步解释该版本的作用。
-
通过置顶来突出重要对话 :Discussinos 支持将对话和公告置顶,这样可以轻松确保您的社区或团队能够访问重要信息。Next.JS 社区就是一个很好的例子,
-
确定社区中的热门话题:您可以根据给定讨论实例中的所有对话获得的赞成票数对其进行排序。您可以按日、月、年或所有时间进行排序。这是一种跟踪哪些对话在您的社区中引发了最大兴趣的好方法。
-
通过问答帖子提出问题并获得答案 :对您正在面临的 pull request、issue 或问题有疑问吗?尝试发布问答讨论以找到答案。最好的部分是:您可以标记哪些回复是有用的答案,以便其他人可以快速找到对您最有帮助的内容。 在mkdocs-material社区中,就是这么做的。
-
协调工程资源:在某些社区中,Discussions 的另一个常见用例是协调团队资源和 sprint planning。不仅如此,您还可以直接从 Discussions 中创建和分配 issue,这让 sprint planning 变得容易(稍后会详细介绍)。
-
举行一般性讨论 :您可以使用讨论来谈论工作(或生活),并通过一般性帖子吸引社区或团队的参与。例如,Next.JS 社区使用讨论来展示哪些公司和网站正在使用其软件。
使用 Github Discussions 的最佳实践
Discussions 功能可让您在存储库中直接使用社区论坛,从而轻松与协作者沟通并促进社区发展。
但我们都知道,成功的论坛需要适度管理,以确保对话保持高效和有益。无论您是为小型团队使用讨论功能,还是将其作为大型开源项目的一部分,以下是一些需要牢记的最佳做法:
-
使用标签让您的空间井然有序。 讨论支持标签,您可以自定义标签以满足您的需求。这些标签可以应用于任何讨论,并可用于显示重要信息,使搜索特定讨论更加容易,并有助于避免重复内容。
-
在 Q&A Discussions 中,标记哪个回复回答了问题。 问答帖子是讨论的一个常见用例,这有助于从您的团队或社区众包答案。但是当您提出问题时,请务必标记哪个回复回答了您的问题。这可以帮助您避免重复内容(或死帖)。对任何有帮助或准确的评论或回复点赞也是一种很好的做法。
-
使用 Discussions 触发自动化:Discussions 支持 GraphQL API,这意味着您可以使用 GitHub Actions 从新的 Discussions 和评论事件触发自动化。常见用例包括在创建新的 Discussion 或评论时触发聊天应用通知,以及向包含关键 Discussions(例如公告)的网站自动发送更新。
-
将协作者转变为版主并为他们分配分类权限。 如果您的社区足够大,将一些协作者转变为版主将对您大有裨益,帮助您保持讨论实例顺利运行。您可以通过为项目中的人员分配分类权限来实现这一点。 这会将他们转变为可以标记答案、管理论坛、远程内容等的版主。
-
使用顶部排序功能查找热门对话。一旦讨论论坛变得足够大,您可能会发现很多日常活动和大量帖子。如果您没有时间浏览每个对话,您可以选择顶部排序功能并将其设置为您喜欢的时间范围(天、周、月、年或全部),查看热门对话。
Github Discussions vs. Github Issues
新接触 GitHub Discussions 的开发人员经常会问这样的问题:什么时候应该使用 Discussions,什么时候应该使用 Issues?
简短的回答:Discussions 非常适合需要团队沟通才能做出决定的问题和想法,而 Issues 则是明确的工作。
稍微长一点的答案:在任何项目或 sprint 中,你都有需要讨论的事情和需要做的事情。Discussions 是为了讨论事情-------这并不奇怪。Issues 是为了在你决定如何前进后,对你需要做的工作进行分类。
什么时候使用 Github Discussions?
GitHub Discussions 最适合用作分享问题、想法、对话、评论请求 (requests for comment RFC)、资源规划和公告的工具。
什么时候使用 Github Issues?
GitHub Issues 用于跟踪具有明确起点和终点的可执行工作。这些工作可以包括新功能、修复错误、常规更新以及跟踪 epics 和 sprints 等。
Issues 和 Discussions 都可以帮助您提高工作效率和协作能力。但是,如果将两者结合使用,您可以更高效地使用问题和拉取请求进行积极工作,使用讨论进行对话、提问和社区参与。
还有另一个好处:您可以在 Discussions 中引用 Issues,这有助于为工作提供背景和上下文。如果您在完成任务之前需要更多信息和决策,您还可以将 issue 转换为 discussion。
如何从 Discussions 中创建 Issue?
Discussions 提供了一个异步通信平台,可以保存历史信息、笔记、想法等。最好的部分是:您可以直接从 discussion 中创建 issue,这意味着您可以将导致某项工作的笔记和决定直接附加到问题中。
为此,请转到右侧边栏并单击Create issue from discussion,然后构建您的问题并将其分配给某人(或您自己)。
如何将 Issue 转化为 Discussion?
说实话:有时人们会将 Issues 用作任何对话(或不涉及可执行任务)的默认地方。其他时候,人们会创建一个问题,然后意识到他们需要团队做出决定才能开始前进。
在这种情况下,您可以通过转到问题的右下角Convert to discussion,并选择将问题转换为讨论。
这样做将关闭并锁定 issue,同时在新的 Discussion 中保留标题、描述和作者。
写在最后
无论您是在规划功能路线图、询问有关您正在做的事情的问题,还是与构建您所使用的软件的开源社区互动,GitHub Discussions 都为所有社区(开源和私人)提供了一个连接和协作的中心空间。
Discussions 旨在做三件事:
- 为对话和提问提供一个集中的社区空间(并使维护人员在处理问题和拉取请求时的生活更轻松)
- 为新手和非代码协作者创建一个参与更大社区的地方
- 突出项目贡献者以帮助培养下一代维护者
现在就尝试在您的公共或私有资源库中启用它,或者与您有兴趣了解的任何开放源代码社区进行互动。