同步操作将从 Gitee Community/开源指北 强制同步,此操作会覆盖自 Fork 仓库以来所做的任何修改,且无法恢复!!!
确定后同步将在后台操作,完成时将刷新页面,请耐心等待。
Issue 的翻译大致为议题、问题。
为了方便你理解,我们更愿意把它称之为待办清单、问题或 Bug 列表、讨论版等等。相信这些称呼会让你更容易理解什么是 Issue。
这是一种伟大的协作方式,让你可以更方便的对整个仓库进行跟踪、增强和排错[1]。对于一个公开的仓库来说,Issue 是向所有人开放的,不仅仓库的所有者可以给自己提 Issue,其他人也可以对项目提 Issue。
而根据 Gitee 官方的建议,项目相关的技术问题、缺陷报告、建议等信息都可以通过 Issue 进行发布。
那么什么情况下需要提交 Issue 呢?
常见的 Issue 面板的使用会有以下几种方式:
待办清单 TO DO LIST
比如你要写一本书,共分为八个章节,你选择使用 Gitee 来管理你的书籍电子稿。那么你需要提前想好每一章节的标题,以及每个章节内的每个小节需要写点什么,并列个提纲。此时,你可以将每一个小节想好要写的大致脉络分别提一个 Issue,用来提醒自己未来要做的事情。(这也是你正在看的这本开源指北
的协作方式)完成后,你只需要按照规划,将每一个 Issue 中所提到的编写任务完成,你的云端书籍也就完成了。
问题列表 BUG LIST
一个复杂的项目难免会有这样或那样的 Bug,而这些内容被观摩你仓库的朋友们发现之后,可以通过 Issue 给你提出,你可以根据他们指出的复现步骤来定位问题,并最终修复,让你所编写的项目更加健壮而强大。不要害怕自己代码写得很烂,感觉别人提 Bug 就是在揭自己的短什么的,因为每发现一个 Bug 意味着你的程序又少了一个缺陷,只需要快速修复它即可。当然,你也可以自己发现 Bug,并给自己提出 Issue,目的是让自己的项目有充分的留痕,便于后续避免该问题或寻找解决方案。
讨论版 BBS
可以完全将 Issue 模块当做你的仓库的私人论坛、私人社区来使用。围绕你的项目,你可以做如下的事情:
求助!女朋友生气了要怎么哄?
当然,第三点的前提是这是你自己的仓库,如果是他人的仓库,请遵守其作者对于 Issue 板块的要求和规定。前文也提到,根据 Gitee 官方的建议,可以通过 Issue 进行发布的内容包括项目相关的技术问题、缺陷报告、建议等信息,这一点请开发者们着重注意,避免一些项目外的信息影响 Issue 板块的正常讨论。
所以,总结下来,可以有如下结论:
那么一个好的 Issue 应该写点什么呢?
这一点对于外部协作者来说尤为重要,因为你要提的 Issue 不是在自己的地盘上,而是需要得到别人的帮助的,所以你尤其要注意 Issue 的礼仪。
请
、谢谢
、Please
、Thanks
等词语。如果你是仓库的拥有者,你还可以编写一个
CONTRIBUTE.md
文件放在项目中,用来告知其他开发者需要如何参与你的项目。
格式:[分类、标签或某文件名] + 简短描述
先使用方括号(也可以使用【】
替代方括号),里面写上分类、标签或某文件名(比如这个文件有问题待修改),这部分是便于作者进行问题分类的,也方便其他协作者查找(很多人提 Issue 并没有这一部分,建议加上)。然后使用简短的描述,可以让人通过标题快速了解这个 Issue 是讲什么内容的。
案例:[Bug]app.py文件 173 行运行报错,疑似遗漏一个=号
咱们先来给一个 Gitee 官方通用的模板:
### 该问题是怎么引起的?
### 重现步骤
### 报错信息
你可以按照模板来补充 Issue 内容,如果你有更详细的描述,当然也可以扩充模板。如果作者有提供 Issue 模板,请按照作者规定的模板提,这样可以方便作者对问题进行后续整理。
Gitee 在提 Issue 时是支持 Markdown 格式的,它让我们提出的 Issue 能有更加丰富的内容展现。
在 Gitee 中,支持在新建仓库时创建 Issue 模板,也支持自定义模板。
在新建仓库时,勾选使用Issue模板文件初始化这个项目
,实际上就是在仓库根目录下新建了 .gitee/ISSUE_TEMPLATE.zh-CN.md
文件,当然你也可以自己创建这个文件,来编写自己的模板。
自己创建 Issue 模板,可在仓库中创建.gitee
目录,并创建对应的模板文件:
.gitee/ISSUE_TEMPLATE.zh-CN.md
,Issue 中文模板.gitee/ISSUE_TEMPLATE.en.md
,Issue 英文模板.gitee/ISSUE_TEMPLATE.zh-TW.md
,Issue 繁体模板Q: 不同类型的模板,有什么作用?
A: 例如你的仓库中有 3 种语言类型的 Issue 模板,提交 Issue 的用户使用的是英文版,那么当用户勾选
使用Issue模板
,则会智能地使用英文模板,如果对方使用的是中文版则会智能地使用中文 Issue 模板。
当你在敲标题或者 Issue 内容时,项目会自动显示已有的类似 Issue,你可以先查看一下推荐的 Issue 能否解决你的问题,如果不能再提出,避免反复提出同一个问题。
好了,当你完成 Issue 主体内容的填写之后,快去提交给作者吧!
下面我们来看几个 Issue 的案例。
无价值:
https://gitee.com/sentsin/layui/issues/I1SS5Z
该案例的标题仅两个字表格
,作者如果不点进 Issue 的具体内容则无法获知到底这个 Issue 说的是什么。属于无价值案例。
https://gitee.com/sentsin/layui/issues/I1PQVC
该案例最抓人眼球的应该是那一长串的!
号,画面都快容不下了,而且作者在看这样的标题的时候也无法获知到底是个什么问题,有一种过分夸张的感觉。属于无价值案例。
有价值:
https://gitee.com/sentsin/layui/issues/I1OFU3
标题清晰明了,作者可以轻松获知 Issue 的主体内容。内容贴出了自己尝试的代码,便于作者提供帮助。属于有价值案例。
https://gitee.com/sentsin/layui/issues/I1OD1P
该案例同样使用了清晰明了的标题表述形式,内容中还具体贴出了自己尝试的代码,便于作者提供帮助或定位问题。属于有价值案例。
从上面的几个简单的案例来看,我们发现无价值的案例都有过分夸张、需要表达的观点或内容不清晰等问题。
而有价值的案例,既能在标题中精准反馈某一个点的问题,又能在内容中贴出自己尝试的代码和想法,便于作者提供帮助。
因此,Issue 的精准表述是能获得良好协作的基础,提 Issue 也是一种很好的练习表达的方式。
掌握了 Issue 的基础使用之后,作为一个优秀的开发者,我们还可以掌握一些进阶的知识,它能让你压榨干净 Issue 的每一分价值。
如果仓库是你自己的,你可以在每一个 Issue 的面板看到更多的进阶选项,如图所示:
负责人:负责人指的是谁来负责处理这个 Issue,可以设置用户为负责人或协作者。对于个人版来说,只能选择自己。如果是组织或者企业,可以指派他人。同一个 Issue 仅能有一个负责人,但问题可能由多个人协作解决,所以可以添加多个协作者。其它权限是一样的。对于企业版用户来说,设置负责人可以很好地统计任务完成情况(个人版无此功能,因此负责人也可以不设置),如图所示:
企业版中可根据负责人统计任务完成信息:
标签:高质量的 Issue 是项目成功的关键。有些人把 Issue 仅仅看作是一堆你不得不去处理的问题列表,但是如果这些问题单管理完善,进行了分类并打上标签,会令人意想不到的提升我们对代码和社区的了解程度,也让我们更清楚问题的关键点在哪里。[2]将标签完善之后,不管是仓库所有者还是其他人都可以快速定位含有某标签的 Issue,协作的效率也将大大提高。
在 Gitee 中,Issue 中的标签支持修改原有标签名称、从其它项目导入标签以及新增自定义标签等。一个默认的仓库会有如下一些默认的标签[2][3]:
如果默认的标签不够你使用,你可以添加你的自定义标签。只需要点击右上角的+
号即可。
项目:项目仅企业版用户可以关联,个人版或组织在这一项可以忽略掉。企业版用户可以根据下面的图片来了解如何创建一个项目,以及如何找到新创建的项目。当项目创建之后,就可以关联到某个 Issue 了。
先进入企业面板,进入所在企业:
右上角新建项目可以新建:
查看新建的项目:
里程碑:里程碑是某功能或某个时间段的一堆问题的集合。比如我们要写一本书,一个章节如果设置为一个里程碑,那这个章节里面的每一个小节我们就可以分别提多个 Issue,最后将这些 Issue 关联到这个章节的里程碑中,方便管理,可以很容易看到整个章节的完成进度。我们可以根据自己的需要,来使用里程碑的功能。下面是一些使用里程碑功能的例子[1]:
如何创建自己的里程碑?(所有用户均可创建)
新建里程碑:
新建完成后即可在 Issue 中关联:
关联分支:这里可以选择关联到该仓库的哪个分支。
计划开始日期:该 Issue 计划开始处理的日期。
计划截止日期:该 Issue 计划截止处理的日期。
置顶选项:该 Issue 在 Issue 列表中的置顶级别。
优先级:该问题的严重程度,优先处理级别。
Issue 在提出之后,对于个人版来说可以有四种状态:待办的、进行中、已完成、已拒绝。负责人或者协作者可以修改该状态。企业版会可选更多的状态。
状态变更之后,允许再次变更,比如设置为
已完成
状态的 Issue,可以再次修改为进行中
。
我们还可以在看板
中看到处于每种状态的 Issue 的列表。
使用@
符号可以在 Issue 提出或者问题讨论的过程中提及别人,起到被 艾特
的效果。
使用#
符号再加上其他 Issue 的编号,可以关联到其它的 Issue。找到本仓库下 Issue 的编号之后写上即可。
找到 Issue 编号(这里为 #I23WUE
):
支持快速点击,提交 Issue 之后会自动生成链接,链接到该 Issue:
可以通过搜索框输入关键词搜索 Issue,也可以通过下方的一些搜索条件来搜索 Issue。有了筛选器,当我们的 Issue 非常多时,我们就可以在众多的 Issue 中找到自己需要的 Issue 了。
当你将各种 Issue 维护好对应的标签之后,可以快速找到属于某个标签的 Issue 结果进行处理。
比如在修复一个 Bug 时,某一次 Commit 就是解决了提这个 Bug 的 Issue 的,那么我们可以轻松的在 Commit 的内容中附带上一些特殊信息(在 Commit 信息中或者附加信息中均可),来自动关闭 Issue。
Gitee 支持的提交方式有(比如我们需要关闭的 Issue 编号为 24,+
号表示在提交的内容中添加后面部分的内容)[4]:
# 任选其一即可!
+ fix #24
+ fixed #24
+ close #24
+ closes #24
+ closing #24
+ closed #24
+ resolved #24
不知道大家是否在 Issue 中有一些任务需要分步骤完成呢?如下面示例的 Issue,可以实现待办清单的功效[4]。可以根据后续的需要,勾选或者取消勾选待办清单中的分项任务,实现 checklist 的效果。
勾选或取消勾选后,刷新页面或者关闭该 Issue 页面重新打开,选择的状态依然存在,而且这种操作会保存到该 Issue 的操作日志当中去。修改状态,不再需要重新编辑该 Issue 了,非常的方便。
那么,需要拥有这样的待办清单,提 Issue 的时候应该怎么写呢?请看代码:
通过特有的语法可以实现待办清单的功效,修改待办清单里面的项目是否完成无需再打开 Issue 的编辑界面了!
* [x] 吃早餐
* [ ] 吃午餐
* [ ] 吃晚餐
通过* [x]
来创建已勾选的事项,通过* [ ]
来创建未勾选的事项即可。
请注意,设置未勾选状态时,方括号之间会有一个空格
[ ]
,不要漏掉了。
[1] https://guides.github.com/features/issues/
[2] https://zhuanlan.zhihu.com/p/75691927
[3] https://blog.csdn.net/lovewinner/article/details/80763629
[4] https://www.jianshu.com/p/5ba1e7f5ad70
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。