GitHub Autolinked references & Permanent link - 团队讨论的专业技巧

在资讯团队进行讨论的过程中，不免会提到相关 Issue、Pull Request 与 程序码。无论是面对面或线上沟通，必须要透过连结或截图画面才正确描述 Issue、Pull Request 与 程序码内容，这些长连结与截图会使得讨论纪录难以阅读，导致开发人员需要花更多时间理解与搜寻想要的资讯，而非专注於原有开发职责。

花在阅读程序码与撰写程序码的比例约 10:1 - Clean Code Robert C. Martin

在 GitHub 有两个看似平凡，在讨论中却扮演着重要脚色的功能： Autolinked references 与 Permanent link。透过这两个通能，与会者可以在讨论 comment 中快速的连结到相关的 Issue、Pull Request 与 特定程序码位置，进而提升团队沟通效率。

Autolinked references

GitHub Autolinked references 能将 URL, Issue, Pull Request 与 Commit 缩短且转换成连结，让讨论串的参与者能透过字面上的意思与连结，快速了解讨论的内容。

在 GitHub 内建立 Issue、Pull Request 与 Comment 皆是透过 markdown 进行编辑，若读者在内容加上标准的 URL， GitHub 会自动帮你加上外部连结，当想拜访这个连结时，不需要自行复制，只需要点选文字即可开启外部网页。

当你想要提到某个 issue 或 pull request，你可以使用 #数字 或 GH-数字 除了出现下拉选单让你选择，内容送出後也会直接帮你加上连结。

下表为所有短网址缩写方法，预设为 Repo 内 issue 与 pull request，也有指定外部使用者与组织的缩写方法

在程序码方面，每次 commit 皆会产生一组 SHA hash，我们可以透过 SHA hash 连结到程序码

不需要完整 SHA hash，只需要前 7 码即可

下表为关於程序码短网址缩写方法

最後，有读者一定会有疑问，若要连接到外部 (非 GitHub 本身) 的网站，或自订连结，该怎麽处理呢?
开启 Repo > Setting > 在左边选单选择 Autolink references > Add autolink reference

输入你要产生短连结的前置文字 (Reference prefix)，目标 URL，点选最下方 Add autolink reference 按钮即完成。以下图举例来说：前置文字 为 TICKET-，在 comment 时使用时输入 TICKET-1，会直接对应到 **https://example.com/TICKET?id=1** 。

我们可以进行测试

Permanent link

眼尖的读者应该发现，虽然 Autolinked references 可以指定程序码，但却不能指定行数，开发人员在进行讨论的时候仍需要自行上拉下拉画面，找到要讨论的位置，相当不方便。GitHub Permanent link 可以解决这个问题。

我们随意开启程序码，选取你要讨论的行号 (或以 Shift 键选取范围：先点起始行数，再按住 Shift 点选其他行号)，会出现 ... 按钮

点选 ... 按钮，选择 Copy permalink

会复制的网址如下：
最重要的部分是 #L1-L6，这里表示的意思为 1-6 行 (倘若只有 #L1，则代表第 1 行)
https://github.com/matsurigoto/ActionDemo-DotNETCore/blob/60c23a57d4f2ebad8404368457944357ca9c13e2/ActionDemo/Startup.cs#L1-L6

阅读完本篇文章，你应该对於 GitHub 上与团队的沟通技巧有进一步的了解，善用短连结可以让成员们更快速找到讨论的焦点与更快进入状况。

若喜欢我的文章，欢迎点 like, 分享与订阅。

参考资料

1. https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls
2. https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet