Coding Style（四）—— GitHub 中 Issues、Pull requests 等使用

文章摘要

GPT 4o

投诉

所有的代码规范、接口设计以及各种规定，都是为了在团队内部形成共识，防止个人习惯差异引起的混乱。

GitHub 当中有不少有用的功能，本文将介绍 Issues、Pull Requests、Discussions、Projects 等功能。

Issues

Use GitHub Issues to track ideas, feedback, tasks, or bugs for work on GitHub.

根据官方文档的说法，Issues 可用于追踪想法、反馈、任务以及 Bug。

在新建 Issue 时，还可以设置 Assignees、 Labels、Projects、Milestone 等属性。

属性	用途
Assignees	指定这个 Issue 的负责人。
Labels	指定这个 Issue 的标签，表示该 Issue 的类型，例如 bug、enhancement、question、help wanted 等。
Projects	指定这个 Issue 的所属项目。
Milestone	指定这个 Issue 关联的里程碑，通常用来表示项目的一个阶段。Issue 不能设置截止时间，但是 Milestone 可以。

在实际使用的时候，每当有新的需求时，建议先创建新的 Issue，再创建对应的功能分支，功能分支的名称可以以 Issue 的编号开头。在任何时候，针对一个 Issue 只能存在一个分支，但一个分支可以解决一个或多个 Issue。

在描写一个 Issue 标题的时候，使用 “As an administrator, I want to remove users without receiving an error” 会比 “Administrators can’t remove users.” 更好。

在 Commit Message 中提到 #n（其中 n 为 Issue 编号，下同）即可将该 commit 与相关 Issue 关联上。更进一步，只要 Commit Message 中出现 close、closes、closed、fix、fixes、fixed、resolve、resolves、resolved 等官方文档中出现的关键词加上 #n，就可以关闭对应 Issue。

Pull requests

Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.

Pull Request 本质上是一种沟通机制。

当你需要反馈的时候，你可以不指定 Reviewers，并在标题中写上 [Draft]、Draft:、(Draft) 等关键词，告知大家这是一个 Draft Pull Request，防止被不小心合并了。
当你需要将合并代码的时候，指定 Reviewers。

在分支开发完成后，大概率会有不少的 Commit 记录，但是在合并到主分支的时候，往往只希望较少的 Commit 记录，方便追溯以及管理。如果该分支由你一个人开发，且该分支没有和主分支合并过，应该把多个 Commit 记录合并成一个（或两三个）。

Discussions

Use discussions to ask and answer questions, share information, make announcements, and conduct or participate in a conversation about a project on GitHub.

GitHub 终于把 Issues 和 Discussions 这功能划分得更加明确了。

在 Discussions 功能出现之前，开发者只能把交流放到 Issues 列表当中，时间久了之后整个 Issues 会变得非常混乱。Discussions 更像是个社区论坛，可以在上面进行提问、发布公告以及分享信息。