所有的代码规范、接口设计以及各种规定,都是为了在团队内部形成共识,防止个人习惯差异引起的混乱。
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 更像是个社区论坛,可以在上面进行提问、发布公告以及分享信息。
# Projects
Projects are a customizable, flexible tool for planning and tracking work on GitHub.
Projects 功能简单说就是提供项目看板,可以将 Issues、Pull Requests 更系统化地追踪,且可以自定义 Workflow。关于 Projects 的最佳实践请参照官网。