一、Issue
- 在软件开发过程中,开发者们为了跟踪BUG及进行软件相关讨论, 进而方便管理,创建了Issue。管理Issue的系统称为BTS(Bug Tracking System,BUG跟踪系统)。当今具有代表性的BTS有RedmineA、TracB、 Bugzilla(http://www.bugzilla.org/)等
- GitHub 也为自身加入了 BTS 的功能。在 GitHub 上,可以将它作为软件开发者之间的交流工具,多多加以利用。遇到下面几种情况时,各 位就可以使用这个功能:
- 发现软件的 BUG 并报告
- 有事想向作者询问、探讨
- 事先列出今后准备实施的任务
- Issue除BUG管理之外还有许多其他用途。在软件开发者的圈子 中,将Issue用于多种用途的情况已经司空见惯。作为GitHub的功能之 一,想必今后会有更多人自然而然地用到它。所以借此机会,让我们来共同学习Issue的一些简单用法
新建Issue
- 在仓库中点击“Issue”,然后点击“New issue”就可以新建一个话题
![]()
![]()
简洁且表现力丰富的描述方法
![]()
![]()
![]()
- 语法高亮:假设我们像下面左图所示,先指定语言再描述代码,这样一来,代码就会如下面右图所示被添加语法高亮,变得直观易读
![]()
![]()
![]()
添加标签以便整理
- Issue可以通过添加标签(Label)来进行整理。在创建一个Issue话题时,可以为该话题设置一个标签,在下图左侧选择
![]()
![]()
- 然后点击“Submit new issue”提交之后,就会话题旁边就会显示这个标签
![]()
- 标签可以自由创建。既可以按语言和技术分类,也可以按照 BUG、任务、备忘等作业类型分类。各位可以按照需要选择便于整理的标签。
- 提个小建议:其实在 Issue 比较少的情况下不必每个都添加标签, 大可等 Issue 积攒到一定数量,只有进行筛选才能清晰把握时再添加标签
添加里程碑以便管理
- 除标签外,还可以通过添加里程碑来管理Issue
- 点击下图中的“Milestones”按钮进入
![]()
- 然后点击“Create a Milestone”就可以创建一个里程碑
![]()
![]()
![]()
![]()
Tasklist语法
![]()
- 这样一来,这段文字就会被标记成复选列表的样式(下图所示)。这 个复选列表可以直接勾选或者取消,不必打开Issue的编辑页面重新编辑,十分方便,建议各位记住这个功能
![]()
通过提交信息操作 Issue
- 在GitHub上,只要按照特定的格式描述提交信息,就可以像一般BTS带有的功能那样对Issue进行操作
- ①在相关 Issue 中显示提交:在Issue一览表中我们可以看到,每一个Issue标题的下面都分配了诸如“#2、#3...#24...”的编号。只要在提交信息的描述中加入“#24”,就可以如下下图所示,在 Issue 中显示该提交的相关信息,使关联的提交一目了然。这里只需轻轻点击一下便可以显示相应提交的具体内容,在代码审 查时省去了从大量提交日志中搜索相应提交的麻烦,非常方便
![]()
![]()
- ②Close Issue:如果一个处于Open状态的Issue已经处理完毕,只要在该提交中以下列任意一种格式描述提交信息,对应的 Issue就会被Close:
- fix #24
- fixes #24
- fixed #24
- close #24
- closes #24
- closed #24
- resolve #24
- resolves #24
- resolved #24
- 利用这个方法,每次提交并push 之后,就不必再大费周章地到GitHub的Issue中寻找相应 Issue 再手动 Close,省去不少麻烦
- 像这样,只要按照特定的格式描述提交信息,GitHub 就会自动识别 并处理,让使用 GitHub 变得更加轻松。目前,很多 GitHub 之外的 BTS 也实现了这一功能,记住它绝对是有利无弊的。
将特定的Issue转换为Pull Request
- 在GitHub上,如果给Issue添加源代码,它就会变成我们下面要讲到的Pull Request。Issue与Pull Request的编号相互通用,通过GitHub的API可以将特定的Issue转换为Pull Request,能够完成这一操作的hub命令会在后面文章讲解。在这里,各位只要先记住Issue与Pull Request的编号通用即可
二、Pull Request
- Pull Request 是用户修改代码后向对方仓库发送采纳请求的功能,也是GitHub的核心功能(下图所示)。正因为有了这个功能,才会让众多开发者轻松地加入到开源开发的队伍中来
![]()
- Pull Request 页面能够列表查看当前处于Open状态的Pull Request。通过点击页面左部和上部的选项可以进行筛选和重新排列
- 在列表中点击特定的 Pull Request 就会进入详细页面(下图所示)。页面上方显示着这次是从谁的哪个分支向谁的哪个分支发送了 Pull Request
![]()
![]()
Conversation
- 在Conversation标签页中,可以查看与当前Pull Request相关的所有评论以及提交的历史记录。人们在这里添加评论互相探讨,发送提交落实讨论内容的整个过程会按时间顺序列出,供用户查看。各位在查看过程中如果有自己的想法,不妨积极地添加评论参与探讨
- 提交日志的右侧有该提交的哈希值,点击链接即可确认相应提交的详细信息
![]()
![]()
Commits
- 在Commits标签页中,按时间顺序列表显示了与当前Pull Request相关的提交(下图)。标签上的数字为提交的次数。每个提交右侧的哈希值可以连接到该提交的代码
![]()
Files Changed
- Files Changed标签页中可以查看当前 Pull Request 更改的文件内容以及前后差别。标签上的数字表示新建及被更改的文件数
- 默认情况下系统会将空格的不同也高亮显示,所以在空格有改动的情况下会难以阅读。这时只要在URL的末尾添加“?w=1”就可以不显示空格的差别
- 将鼠标指针放到被更改行行号的左侧,我们会看到一个加号。点击这个加号可以在代码中插入评论(下图)。这样,评论是针对哪行代码的就一目了然了
![]()
三、Wiki
- Wiki 是一个使用简单的语法就能编写文档的功能。所有有权限的人都可以对文章进行修改,所以比较适合多人共同编写文章的情况。创建、编辑文档时不必另外启动软件,用起来十分方便,非常适合用来针对更新频率较高的软件进行文档等信息方面的汇总
新建Wiki
- 与 Issue 和 Pull Request 相同,Wiki也支持GFM语法,所以可以轻松创建表现力丰富的文档
- 点击页面右上角的 New Page 按钮便可以创 建新的Wiki页
![]()
![]()
clone编辑
- Wiki功能本身的数据也在Git中进行管理
- 点击Clone URL按钮可以将当前Wiki的Git仓库URL复制到剪贴板中。用户能够通过clone操作获取Wiki仓库,然后在本地创建、编辑页面,进行提交再push, 便可以完成对Wiki的创建及编辑工作
- 例如下面是一个Wiki的实例,链接如下:
https://github.com/dongyusheng/git-tutorial.wiki.git
![]()
Pages标签
- 在Pages标签页中可以列表查看Wiki页面
- 例如本仓库只有一个Wiki文章,因此Pages标签中只有一个
![]()
侧边栏
- 所有Wiki页面都可以显示侧边栏。做法很简单,只要创建名为“_sidebar”的页面即可。_sidebar页不会显示在Pages的页面一览中
- 点击右侧的“Add a custom sidebar”既可以创建
![]()
- 在编辑各页面时页面下部会附加Sidebar 段(下图所示), 用户可以在这里编辑侧边栏的内容
![]()
四、Pulse
- Pulse是体现该仓库软件开发活跃度的功能。近期该仓库创建了多少Pull Request或Issue,有多少人参与了这个仓库的开发等, 都可以在这里一目了然
![]()
- 根据这个页面,用户可以判断目前这个软件是否正在被积极开发, 或者持有仓库修改权限的人是否在认真地进行BUG修正等维护工作。 在挑选GitHub上开发的软件时,它可以作为一个重要的衡量标准
active pull requests
- 页面中Overview的左半部分显示了特定期间内活动过的Pull Request 数
- 下图中:
- 0个 Pull Request
- 其中有0个被采纳(Active Pull Requests),0个保持Open状态(Proposed Pull Requests)
- Proposed Pull Requests将来要么会被采 纳,要么会被Close
![]()
- 如果想查看清单的详细内容,只要点击对应项即可(但是此处演示案例没有)。Pull Request 的概要及链接按照合并的先后顺序排列
- 点击 proposed-pull-request 则可以按创建的先后顺序查看 Pull Request 的概要及链接
- 通过这些信息,用户可以了解该软件最近正在开发哪些功能。如果 发现对方正在进行功能扩展或者修正,不妨积极试用一下这个功能。这 或许会成为您加入开源软件开发的契机
active issue
- 页面中 Overview 的右半部分显示了特定期间内活动过的Issue数
- 下图中:
- 有2个Issue,其中有1个被 Close,其余1个仍处于 Open 状态
![]()
- 如果想查看清单的详细内容,只要点击对应项即可。Issue的概要及链接按照 Close 的先后顺序排列
- 点击 new issue 则可以按创建的先后顺序查看 Issue 的概要及链接
- 通过观察 Issue 的整体动向,用户能够知道这个软件是否有人在积 极地维护与支持。对方仓库越是活跃,用户发送的 BUG 报告和相关探 讨越可能收到回应
commits
- Overview下方显示的是与提交相关的信息
- 左侧部分包含了如下几类信息:
- 编写过代码的人数
- 提交的次数
- default branch 中修改过的文件数
- default branch 中添加的行数
- default branch 中删除的行数
- 通过这些信息,用户可以大致把握该仓库中活跃开发者的人数
- 另外,右侧图表显示了这些开发者具体发送的提交数。通过图表我 们可以了解到有哪些开发者在格外积极地向该仓库发送提交
![]()
五、Graphs
- Insights页中,可以通过多种图表查看该仓库的相关统计信息。利用图表直观地汇总信息,可以让用户把握当前仓库的各种趋势
Contributors
- 在Contributors的图表中,我们可以看到每个用户在相应日期中发送提交、添加代码、删除代码的大致数量
- 从这里我们能够 了解到该仓库的代码主要由哪些人编写。而且,还可以通过图表分析出该软件大幅修改阶段和稳定维护阶段的相应时期
![]()
- 另外,这些图表的统计中还包括发送 Pull Request 被采纳后产生的 代码增减
Commit Activity
- Commit Activity 中显示了一年内(52 周)每周收到的提交的大致数量
- 第二张表中还可以查看相应周每天的提交数量。判断某 个仓库是否有人在积极更新时,这部分是一个重要的指标
![]()
Code Frequency
- Code Frequency中显示了该仓库中代码行数的增加量和删除量
- 一款优秀的软件并不会一味地增加代码,在经过重构之后,代码量往往会降低。通过这张图,我们可以直观地把握相应信息
![]()
Network
- 以图表形式显示包括克隆仓库在内的所有分支的提交。 从图上可以直观地看出每个人做了多少工作
- 将鼠标指针停留在表中提交或合并的点上,可以查看相应的参考 内容
![]()
六、Settings
- 在这里可以对仓库进行任何设置。用户必须拥有更改设置的权限,才能看到这个页面
Options
- ①Settings:
- 在这里可以修改仓库名称
- 上传社会预览:上传一张图片,定制你的存储库的社交媒体预览
![]()
- ②Features:这里可以更改Wiki 和 Issue 的相关设置。如果想关闭某些功能,只要取消已勾选的相应复选框,该功能就会从菜单中移除,无法使用
![]()
- ③GitHub Pages:
- GitHub有一个名为GitHub Pages的仓库,用户可以利用该仓库中的资料创建Web页,用来发布仓库中软件的相关信息。如果已经创建过GitHub Pages,则会显示相应URL
- GitHub Pages 主要用于在GitHub上托管静态 HTML,以便发布项目的 Web 页(https://pages.github.com/)
- 由于可以绑定独立域名,人们也经常利用结合了这个功能的 OctopressB 框架来搭建博客。有兴趣的读者不妨试一试
![]()
- ④Danger Zone:这里都是一些需要格外留意的设置。在这里,用户可以将仓库改为私有或是变更仓库所有者,甚至删除仓库本身。这些设置有可能影响到其他人,在变更时一定要谨慎
![]()
②Branches
- 功能分别为:
- 设置显示仓库 URL 时默认显示的分支。这个默认分支同时也是创建 Pull Request 时的默认值,如果各位的主分支不是 master 分支,建议更改这一设置
- 分支保护规则。定义分支保护规则来禁用强制推送,防止分支被删除,并在合并之前有选择地要求检查状态
![]()
③Webhooks
- 在这个页面中,用户可以添加Hook让GitHub仓库与其他服务集成。通过 Add webhook 可以添加用户自己的 webhook
![]()
④Deploy Keys
- 在这个页面中,用户可以添加用于部署的公开密钥,允许以只读方式访问仓库。设置公开密钥后,用户可以使用私有密钥通过 ssh 协议 clone 仓库
- 要注意的是,这里添加的公开密钥·私有密钥对无法再添加到其他仓库。使用Deploy Keys功能时,需要给每个仓库赋予不同的密钥对
![]()
Notifications
- 第一次点进去时,会让你设置电子邮件地址,以便在触发推送事件时接收通知
![]()
- 每当创建 Issue、收到评论、创建 Pull Request 等情况发生时,我们就会在 Notifications 中收到通知