熟练使用Issues

声明

Github官方声明

This document is an unofficial translation of https://guides.github.com/features/issues/ and is not endorsed, maintained or overseen by GitHub. For official Help articles, please visit https://guides.github.com.

译者声明

本译文仅供参考,如有疑问请联系(chaoyanglius@outlook.com)译者或者参考原文https://guides.github.com/features/issues/,感谢您的支持。本作品采用本作品采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可,如需转载请遵守该协议内容并附上原文链接。

简介

添加Issues是一种为你的项目跟踪任务(tasks)、强化(enhancements)以及bug的利器。它们有点类似于邮件,除了它们可以与团队的其他成员分享和讨论。大多数软件项目都会有某种bug跟踪器。而Github的跟踪器叫做Issues,在每个仓库上都会有自己的Issues部分。

github-issues

例如,我们可以看一下bootstrap仓库的Issues部分

bootstrap-issues

因为Github强调合作、引用和美观的文本格式,所以它的issue跟踪十分特殊。下面是一个典型的Github issue:

issue

  • title(标题)和description(描述)描述了这个issue是关于什么的.

  • 不同颜色编码的labels(标签)可以帮助你对issues进行分类和过滤(就像邮箱中的标签一样).

  • milestones(里程碑)就像issues的容器一样。这对于关联特定特点或者项目阶段的issues十分有用(例如Weekly Sprint 9/5-9/16 or Shipping 1.0)。

  • assignee(受委托人)负责在任何指定的时间解决相应的issue.

  • Comments允许访问仓库并提供反馈.

Milestones, Labels, and Assignees

一旦你添加了足够多的issues,你就会发现你很难找到你所关注的issues。有了Milestones, Labels, and Assignees你就可以轻松地对issues进行分类和过滤。

你可以通过点击右侧边栏上相应的齿轮,来改变或添加milestone, assignee, and labels。

add-mla

如果你没有看到编辑按钮,那是因为你没有编辑issue的权限。你可以请求仓库管理者将你添加为合作者来获得相应的权限。

Milestones

milestone

milestones(里程碑)是对应于项目,功能或时间段的issue组。人们在软件开发时,可以以不同的方式使用他们。下面是Github上的一些例子:

  • Beta Launch — 在你发布项目的Beta版之前,你需要修复的文件bug。这样就能确保你不会漏掉什么。

  • October Sprint — 你应该在八月份之前解决的issues。这样当你有很多事要做时,你可以更好地集中精力。

  • Redesign — 涉及到重新设计项目的issues。这是一种收集想法的好方法。

Lables

label(标签)是管理issues类型的很好的方式。一个issue可以有多个label,而且你也可以一次通过多个label过滤出你想要的issue。

labels

Assignees

每个issue都会有一个assignee(受委托人)——负责推进issue的人。选择Assignees的方法与选择milestones的方法相同,都是通过issue上方的灰色栏。

Notifications, @mentions, and References

通过在issues中使用@mentions和references,你可以通知其他GitHub用户和团队,以及交叉连接issues(在一个issue中提到另一个issue)。这些提供了一种灵活的方式来让合适的人有效地解决问题,并且易于学习和使用。它们可以在GitHub中的所有文本中起作用——因为它们是GitHub Flavored Markdown文本格式化语法中的一部分。

intro-nmr

如果你想了解更多,可以看看Mastering Markdown.

Notifications

Notifications(通知)是GitHub中随时了解你的issues的一种方式。通过它们,你可以找到仓库的新issues,或者知道什么时候有人需要你来推进issues。

有两种收到notifications的方式:通过邮箱和网页。你可以在你的设置中配置你接收notifications的方式。如果你计划收到很多notifications,我们推荐你在Participating中设置为web(网页)+email(邮箱),而在Watching中设置web(网页)。

notifications-setting

通过这些设置,当人们特别提及您时,您会收到电子邮件,然后访问基于网络的界面,就可以随时了解您感兴趣的仓库。

你可以通过notifications界面来访问你的notifications。这个界面对于一次浏览多个通知十分方便,而且也可以将通知标记为已读或者屏蔽消息。你可以使用快捷键来加快你的工作流程——在github页面下按下键盘上的?你就可以看到有哪些快捷键了。

notifications

被屏蔽的消息不会在以未读的状态出现,直到你再次被特别地@mentioned(提到)。这样你就可以屏蔽那些你不感兴趣的线程(可能是你不熟悉的子系统)。如果你将某个issue标记为已读,如果有人再次对这个消息进行评论的话,它的状态就会改变。

GitHub也会通过邮箱来同步已读/未读状态——如果你在你的邮箱客户端读了一条notification,那么在网页界面上的notification就会自动标记为已读(如果你喜欢这个功能,你就要确保你邮箱客户端允许显示图片)。

@mentions

我们可以通过@mentions在Github issues引用其他Github用户。我们可以在任何issues的描述或评论中使用它,也可以@username来向另一个Github用户发送notification。这很像twitter中的@mentions。

我们比较喜欢使用/cc语法将人们包含在issue中:

It looks like the new widget form is broken on Safari. When I try and create the widget, Safari crashes. This is reproducible on 10.8, but not 10.9. Maybe a browser bug?

/cc @kneath @jresig

如果你指定要包括的人的话,它的效果会非常好,但是许多情况下,我们是跨团队工作,可能并不知道谁会帮助我们。@mentions对于GitHub组织中的团队也是起作用的。如果你在@acmeinc组织(organization)中创建了一个叫做browser-bugs的团队,你也可以通过@mentions来引用这个团队:

/cc @acmeinc/browser-bugs

这样的话就会给团队的每个成员发送notifications。

References

issues经常是独立于其他issues的,或者至少与其他有关系而且你想将它们连接起来。你可以通过输入井号(#)+issue编号来引用issues。

Hey @kneath, I think the problem started in #42

如果你想包含其他仓库的issues,你可以在前面加上仓库的名字,比如像这样:

kneath/example-project#42

有一种引用issues的更有趣的方式就是直接从commits中引用issues。你可以在提交信息中包含issue编号。

commit-issues

当你将提交合并到master分支时,以“Fixes”, “Fixed”, “Fix”, “Closes”, “Closed”, 或者“Close”开头的commits信息会自动关闭相应的issues。

引用这一功能将正在完成的工作与正在跟踪的bug紧紧联系在一起,而且它是也将项目历史得以可视化的好方法。

搜索

在每个页面的上方是一个搜索框,你可以通过它来搜索issues。

search-box

你可以通过下面的方式检索搜索结果:

这篇关于查找issues的帮助文档会向你展示其他的搜索方式:使用创建或更新日期,标签,作者,评论数量,仓库主人或者更多。

概况和报告

在这个issues部分之外,还有两个页面用于帮助总结如何在你的仓库以及所有你的仓库中处理issues。

issues面板

如果你正在寻找一个包含更多项目的所有issues的列表,issues面板将是一个非常好的工具。这个面板的工作方式与issues部分非常相似,但是收集的issues的方式是不同的:

  • 所有你拥有的和参与的仓库的issues
  • 被分配给你的issues
  • 你创建的issues

如果你使用了organizations(组织),那么issues面板就会为每个organization划分一个issues面板。

Pulse

在每个仓库下面都会有一个叫做Pulse的部分——Pulse是该仓库过去一周(或者一天或者三个月)发生的所有活动的快照。

pulse

通过它,你可以在你离开一段时间后,很快地赶上仓库进度并且不想在关注仓库时接收频繁的notifications。

issues的其他用法

issues可以用来跟踪各种东西——并且GitHub是一个上分享和合作issues的好地方。下面是一些我们最喜欢做的:

结尾

祝贺你读完了这么长的文章!issues管理器在任何开发者的处理中都是一个强有力的工具。我想现在要做的就是修复你的bug了。