Github Issues and PR

这篇文章主要介绍了如何在github上创建issue和PR，以及如何在github上进行代码review，比较基础。

我们还会提到每个仓库/组织中的project这个概念，其实很简单，就是make a plan.

Issues

在进入 Issues Tab 界面后，我们可以看到全部的issue，包括open（尚未解决仍开放）的和closed（已经解决并关闭）的

Issues Tab

在这个界面的右上角，我们可以看到：

1. New issue: 创建一个新的issue
2. Labels: 这个仓库所有issue的标签分类
3. Milestones: 这个仓库所有issue的里程碑分类
4. Filter: 对issue进行筛选
   • 我们可以根据author、label、project、milestone、assignees、status等进行筛选

Inside a Issue

我们需要着重介绍一下右边的菜单栏：

1. Assignees: 指定这个issue的负责人，需要他来解决这个问题
2. Labels: 给这个issue打上标签，方便我们对issue进行分类
   • 常见的标签有：documentation / bug / enhancement / good first issue / help wanted / question ...
3. Projects: 将这个issue加入到项目中，方便我们对项目进行管理
   • 我们可以在Issues Tab旁边发现Projects Tab，点击进入后，我们可以看到全部的项目
   • Projects 如何使用将会在本文第三部分进行展开
4. Milestone: 里程碑，方便我们对项目进行管理
   • 我们可以在 Issues Tab 旁边发现 Milestones Tab，点击进入后，我们可以看到全部的里程碑
   • 里程碑，顾名思义，当项目实现某些重大进展/预期实现某些重大进展，就会记做一个里程碑
5. Development: 开发相关
   • 我们可以将这个issue链接到某个现有的PR里，表示：当我们完成这个PR后，这个issue就会解决
   • 我们也可以在这里，对这个issue单独创建一个PR，表示：这个PR与这个issue相关

issue内的整个界面：

选择issue对应的Project：

选择issue对应的Milestone：

链接issue至PR：

Pull Request

Pull Request 是指，当我们在自己的fork仓库中，修改了某些代码，并且希望将这些代码合并到原仓库中时，我们就可以发起一个Pull Request，简称PR。

Good Dev Process

一个良好的代码开发习惯是，我们在修改代码之前，先创建一个issue，然后在issue中描述我们的修改意图，然后再创建一个PR，将我们的修改提交到原仓库中。

然后由原仓库的maintainer来审核我们的修改，如果通过，就会将我们的修改合并到原仓库中，如果不通过，就会要求我们修改后再次提交。

这里 PR Tab 的 主界面 / 内部陈设 跟issues近乎一样，省略之。

我们需要从 “用户”(developer) 和 “仓库维护者”(maintainer) 的角度来看待PR，我们采用的术语是，在PR互动的过程中要遵守“开发者规范”。

Developer View

作为PR的提出者，很显然我们在这个PR帖子里需要表述清楚，并与maintainer积极互动，以便maintainer能够快速地审核我们的PR，并且能够给出合理的建议。

规范起见，我们的PR需要设置Reviewers进行审核，我们可以在这个页面的右边菜单栏设置reviewers。

在设置后，他们会自动收到一封“need to review”的邮件，这封邮件由github抄送。

至此，我们的PR就已经提交成功了，接下来就是等待maintainer的审核了。

Maintainer View

作为PR的审核者，maintainer需要对PR进行审核，并且给出合理的建议。

Terminology in Open-Source

互动的内容就不说了，我们提供一些常见的开源互动术语，这会极大的提升我们的互动效率，也显得很geek :)

1. WIP: Work in progress, do not merge yet.
2. LGTM: Looks good to me.
3. SGTM: Sounds good to me.
4. CC: Carbon copy. 表示抄送的意思，希望某人也能收到，了解相关信息，通过 cc 后续的 @ somebody，使得他可以在自己的通知中收到相关信息
5. TL;DR: Too Long; Didn't Read. 原文档太长，懒得看，看我来缩略一下。有很多文档在做简略描述之前会写这么一句
6. PTAL: Please take a look. 帮我看下，一般都是请别人 review 自己的 PR
7. DNM: Do not merge.
8. CL: Changelist. 修改的文件
9. CS: Changeset. 和 CL 类似
10. ACK: acknowledgement. 我知晓了，同意！
11. RFC: request for comments. 我觉得这个想法很好, 我们来一起讨论下
12. IIRC: If I recall correctly. 如果我没记错的话
13. IIUC: If I Understand Correctly. 如果我理解正确的话
14. NACK/NAK: negative acknowledgement. 我不同意
15. TBR: To Be Reviewed. 提示维护者进行 review
16. TBD: To Be Done (Defined/Discussed/Decided/Determined). 根据语境不同意义有所区别，但一般都表示还没搞定，有待商榷
17. IMO: In My Opinion.
18. IMHO: In My Humble Opinion IMO. 谦虚的说法，以我的拙见（多用于邮件和网络）
19. AFAIK/AFAICT: As Far As I Know / Can Tell.
20. FYI: For your information. 供你参考
21. AFK: Away From the Keyboard. 稍等，马上回来
22. IANAL: I am not a lawyer, but I smell licensing issues. 我不是律师，但是我嗅到了许可问题的气息 :)
23. Left several nits: 还有几个小缺陷（nits在open-source里表示无伤大雅的小笔误）
24. RTFM: Read The Fucking Manual. 请先阅读相关文档
25. STFW: Search The Fucking Web. 请先搜索相关信息
26. FTFY: Fixed That For You. 我已经帮你修正了
27. LAMO: Laughing My Ass Off. 笑死我了
28. ATM: At This Moment

Code-based Review

我们可以在这里对代码进行审核，并且给出合理的建议。

1. 左边绿色表示新加的文件内容，黄色表示修改的文件内容，红色表示删除的文件内容。
2. 每一个修改的文件条目，都会有一个Viewed表示，点击则表示此处更改已经被审核过了，没问题。
3. 如果发现问题，我们可以在每一个修改的文件条目下，对进行代码审核（Viewed旁边💬符号），并且给出合理的建议。
4. 这个审核主页面的右上角显示了 审核进度 以及 是否审核完毕.
   • 8 / 8 files viewed表示审核进度
   • Review changes 表示审核完毕，可以给出合理的建议

这里Review changes写完评论后有三种模式进行提交：

1. Comment: 只是给出建议，不会影响到PR的状态
2. Approve: 表示审核通过，但是不会合并到主分支
3. Request changes: 表示审核不通过，需要修改后再次提交

一般来说Approve的下一步就是Merge了，ready to go!

Set Branch RuleSet

作为仓库的维护者，我们肯定不希望有人直接在main分支上提交代码，或者未经允许就自行merge的行为。

这些激进且缺乏素质的行为（当然也有可能是代码小白不懂规矩），会导致main分支的代码不稳定，所以我们需要设置一些规则，来限制开发者的提交，以防万一。

基于这些考量，github提供了RuleSet的功能，我们可以在这个页面设置规则，来限制开发者的提交。

在仓库主页面中点击进入Settings，然后点击Branches。我们可以发现Branch protection rules并在这里选择Add branch ruleset

在这个界面，我们可以做很多规则设置：

1. Ruleset Name: 规则集的名称，可以自定义
2. Enforcement status
   • Active: Rules will be enforced
   • Evaluate: For enterprises, ignored here
   • Disabled: Do not evaluate or enforce rules
3. Bypass list: 哪些人是“贵族”，可以不受这个规则制约
4. Targets: 规则的目标，可以是分支，也可以是pattern
5. Rules: 规则的内容，可以是很多种，我们这里只介绍一些常见的规则
   • Require a pull request before merging: 在合并之前，必须有一个pull request，不能直接push到main分支
   • Require approvals: 在合并之前，必须有一定数量的approvals by reviewers
   • Block force pushes: 不允许强制推送

结束设置后，点击最下方的create即可完成全部RuleSet设置

这里提供一些笔者常用的RuleSet

1. Enforcement status: Active
2. Targets: main
3. Bypass: Organization Admin and Repository Admin
4. Rules:
   • Restrict deletions
   • Require a pull request before merging
     • Required approvals 设置成1
   • Block force pushes

Projects

Projects是github提供的一个项目管理工具，可以用来管理项目的任务，也可以用来管理项目的版本/文档。

Built like a spreadsheet, project tables give you a live canvas to filter, sort, and group issues and pull requests. Tailor them to your needs with custom fields and saved views.

你可以在这里设定组织/仓库的进度规划，也可以设定个人的计划；你可以选择将这个project设置成public或private.

我们可以在创设project的时候选择合适的模板，别的就没什么了，这一部分非常简单