使用GitHub issues

W3C国际化标准计划使用GitHub issues进行技术讨论,本文档为刚接触GitHub的人介绍了如何处理issue。

首先要说的是,GitHub issue非常简单和直观!虽然GitHub在处理软件或文档的历史时有时会涉及复杂的操作,但GitHub issue的使用并不复杂

阅览issue

每个GitHub仓库都有一个指向issue列表的链接。下图显示了日文布局任务团的仓库主页,点击蓝色圆圈处就可以访问issue列表。

GitHub界面

点击该选项卡后,你将看到如下的页面,其中列出了所有当前未解决的issue。(单击“2 Closed”将显示所有已关闭的issue。)

GitHub界面

如果需要,可以使用页面顶部附近的控件过滤或排序列表的内容。你可以通过单击标签(如question)查看带有特定标签的所有未解决issue。

点击issue的标题以查看讨论内容。例如,如果你点击上面列表中的第三个标题,你会看到如下内容。

GitHub界面

向issue添加评论

在issue底部的文本框(见上图)中输入内容即可为issue添加评论。

如果你喜欢的话,你也可以在文本中添加Markdown或点击工具栏上的图标为你的评论添加格式。

写完评论后,使用Preview选项卡检查你的评论,然后点击Comment按钮即可评论。

请注意,GitHub会将评论中的尖括号视为HTML标记,因此如果你想包含源代码示例,你应该在源代码两边加上反引号(`)。

此外,如果你想回复issue中的某个较早的特定句子或段落,请将其复制到你的评论中,并在行首添加一个大于号 (>)。GitHub将会为该文本提供灰色背景。

你也可以尝试使用输入框上方的图标来发现其他编辑辅助工具。

跟踪讨论

如果你评论了某个issue,你将自动订阅该issue,并因此在有新评论时收到电子邮件通知。

如果你尚未发表评论,GitHub会提供一个Subscribe按钮(仅用来通知你这个特定issue的更新)或页面顶部的Watch按钮(通知你该仓库中任何issue的更新,以及拉取请求)。

不过,你还应该考虑订阅你关注的仓库的邮件列表。具体的邮件列表会在仓库主页上的说明文本中注明。订阅邮件列表后,你将每天收到一封摘要邮件,其中包含该仓库过去24小时内所有有更新的issue链接。这些摘要也会指出其他仓库中的相关讨论(如CSS和HTML)。

创建一个新issue

任何人都可以提出新issue。 只需单击New issue按钮,添加一个简短但有意义的标题,然后在提供的框中写下你的评论即可。

等待用户输入内容的新issue截图

只有具有管理权限的人才能为issue分配标签。当你创建了一个新issue,他们会收到通知并将决定为其分配哪些标签。

礼仪和小技巧

请记住以下几点:

  1. 在评论之前仔细考虑,并在提交之前重新读一遍。尽量使内容清晰和简洁。

  2. 始终关注主题。如果你还想提出其他问题,请开一个新的issue。目标是让每一个issue都专注于特定的主题。

  3. 在你的评论中始终保持礼貌和建设性。

  4. 即使某个用户没有关注这个问题,你也可以在他们的GitHub用户名后面加上@符号来让GitHub通知他们,如:“@r12a 你觉得这个主意怎么样?”。