# 2022-32: Github 实用小技巧

今天跟大家聊聊我经常使用的 Github 实用小技巧：

- 引用 GitHub Issues/PR/Discussion
- 使用 Fix / Close 来关联一个 Issue
- 可折叠的区块
- Draft / Ready for review
- 请求 Review
- 引用回复

## 引用 GitHub Issues/PR/Discussion

在 GitHub 的任何编辑框都可以使用 `#` + Issues/PR/Discussion 数字 ID 的形式来引用：

![](https://xuanwo.io/reports/2022-32/1.png)

不过我更喜欢直接粘贴对应的链接（不需要使用任何 Markdown 语法，直接粘贴即可）：

![](https://xuanwo.io/reports/2022-32/2.png)

这个功能同样适用跨 repo 的引用：

![](https://xuanwo.io/reports/2022-32/3.png)

## 使用 Fix / Close 来关联一个 Issue

在 PR 中可以使用 `Fix #xxx` 的语法来关联一个 issue，当 PR 被 Merge 的时候，能一同 close 对应的 Issue。

- 可以使用的关键词非常宽泛：[close|fix|resolve][s|ed] 的任意组合都可以
- 注意关联多个 issue 的话需要重复写 `fix #xxx`：`fix #xxx,#yyy` 是不起作用的，只有第一个会生效
- 有 Repo 权限的维护者也可以在侧边栏手动关联：不过感觉不是特别好用，有些 issue 搜索不出来

文档参见：[Linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)

## 可折叠的区块

在 Issues 和 PR 中有时候会想展示折叠的内容，比如长长的完整日志，详细的结果等，这时候可以使用 HTML5 中增加的折叠语法：

```markdown
<details>
<summary>Summary Goes Here</summary>

...this is hidden, collapsable content...

</detials>
```

显示效果如下：

![](https://xuanwo.io/reports/2022-32/4.png)

不过使用的时候需要注意内容跟 `<details>` tag 留一个空行，否则有些 Markdown 语法无法正常渲染。

参见: [Using <details> in GitHub](https://gist.github.com/ericclemmons/b146fe5da72ca1f706b2ef72a20ac39d)

## Draft / Ready for review

如果想要标记 PR 当前仍在工作中，不要进行 review 或者 merge 的话，可以使用 GitHub 原生的 Draft / Ready for review 工作流。

创建 PR 的时候选择 `Create draft pull request`：

![](https://xuanwo.io/reports/2022-32/5.png)

当 PR 准备好 review 时，点击 PR 最下方的 `Ready for review`：

![](https://xuanwo.io/reports/2022-32/6.png)

这样做的好处是不需要引入外部的 bot 和 actions，也不需要作者手动更新 PR 标题，GitHub 会保证这个 PR 无法被 merge。

## 请求 Review

推荐使用 GitHub Request Review 机制来请求维护者 Review：

![](https://xuanwo.io/reports/2022-32/7.png)

点击那个小圆圈会发起 re-request，通知 Reviewer 当前 PR 已经准备好了。

通过这种方式发起的 Review 请求会在维护者的通知中有专门的标记：

![](https://xuanwo.io/reports/2022-32/8.png)

这能够避免比淹没在一堆 `commented` 和 `mention` 之中：热门项目的维护者每天可能有上百个通知，他们很多时候会使用过滤器来过滤出 `review requested` 的通知。

## 引用回复

在 GitHub 上回复评论时请尽可能避免全文引用，只选择自己具体想回应的话：选中自己想要回复的话，然后点开 comment 的菜单，选中 `Quote Reply`

![](https://xuanwo.io/reports/2022-32/9.png)

然后就会自动跳转到回复框：

![](https://xuanwo.io/reports/2022-32/10.png)

这样做的好处在于：

- 避免 Issues / PR 被无用的信息刷屏
- 回答更精准，更能让读者知道当前在回复什么东西

> 推友 [@_a_wing](https://twitter.com/_a_wing) 指出可以使用快捷键 `r`：
> 
> - 选中想要回复的文字
> - 点击一下字母键 `r` 即可快速回复
>
> 亲测有效，比鼠标点击菜单更快，推荐使用