关于如何更好地使用Github的一些建议
关于如何更好地使用Github的一些建议
原文(Github repository形式): https://github.com/Wasdns/github-example-repo
本文记录了我对于Github使用的一些技巧,并针对以下几个方面:
- 一、提交问题;
- 二、提交(commit)的注释信息;
- 三、README形式的Github文档撰写。
给出了自己的一些建议,不足之处欢迎各位指出,欢迎补充和提问:)。
一、提交问题
在提问之前,请确认你的问题是否能够通过以下方式解决:(1)百度;(2)bing;(3)Google;(4)Stackoverflow。
一个参考的主要提问步骤分为:
- (1)标题:出现bug的概要,例:"在根目录下,某某文件无法找到"
- (2)背景介绍(可选):介绍你大概的目的是什么;例:"为了测试数独,我做了这个实验,遇到了这个问题。"
- (3)实验环境:你的系统环境、安装的依赖,选择性给出;例:"我的操作系统为Ubuntu 14.04,64位。"
- (4)重要:重现bug的步骤,尽量条理清晰、简明;
- (5)期待出现的行为(可选):如果没有遇到这个bug,你希望得到的结果是什么;
- (6)结果出现的行为:较为全面的bug信息,或者错误日志,或者二者兼具;
- (7)额外信息:一些附加的信息,如代码(简短的骨架,或者以站外链接的形式贴出),或者你对于该错误的认识;
- (8)礼貌用语。
错误示范:WTF the bug is?
参考样例:"error: HashAlgorithm.csum16: Invalid enum tag"
二、提交(commit)的注释信息
对于一个commit来说,一个完备的注释信息有助于让其他人了解你的这次提交做了什么工作。例如,项目管理员对PR进行code review时需要对于该PR的每一次提交进行审核,如果每次提交的注释信息都非常简单/杂乱,那么对于code reviewer来说是非常不友好的:他需要翻看你每一次文件的修改记录来判断你的这次提交做了什么工作。
一个规范的commit有这样的几个特点:
- 1.注释信息的标题有一句清晰的概述,且主体内容简洁明了;
- 2.注释信息的拓展描述中,对于每一处的修改都有清晰的记录;
- 3.注释信息应保留必要的信息。
1.注释信息的标题有一句清晰的概述,且主体内容简洁明了:
标题至少需要有一句完整的句子(建议少于50字)来说明本次提交做了哪些工作。在大部分同学的github中,每次提交的注释信息通常只有"更新"、"修改"几个单词,其他开发者自然很困惑:到底你更新了什么、修改了什么?只能通过查阅详细信息来查看这次commit的具体修改。一个参考的规范注释信息标题的格式为文件名:简述改动信息
。
错误示例:fix bug
,更新
,发布
;
参考示例:文件名:简述改动信息
,如:README.md: 更新第三章,加入了对commit注释信息的描述
。
此外,要求注释信息的主体内容在能让别人看懂的情况下尽量简洁明了,不加入过多的不必要信息。
错误示例1:我把今天志玲女神写的代码给删除了。
其中今天志玲女神写的代码
是不明确且不必要的,而且没有体现出本次提交的目的。
参考示例2:修改"你今天真好看"功能的API:删除了文件hello.c中的函数模块printBeauty(),修改了函数hello()的返回参数类型。
错误示例2:今天客户A那货提出了一个需求叫做"你今天真好看",后面的同学注意了,我把原来文件hello.c中的一些功能做了适配,来支持这个新功能。
参考示例2:增加"你今天真好看"功能:修改hello.c中函数hello()的返回参数类型。
2.注释信息的拓展描述中,对于每一处的修改都有清晰的记录:
如果一个提交修改了项目中的多个文件/模块,可以将这些修改的共同点,如加入新功能"你今天真好看"
,作为提交注释信息的标题,并将这些修改的具体信息在注释信息的文本栏中分点列出。
错误示例:
Commit Title:
按今天客户A的需求加了一个新功能
Commit Content:
修改了文件hello.c, beauty.c, stupidClient.c。
参考示例:
Commit Title:
2017/10/1:加入新功能"你今天真好看"
Commit Content:
1.修改文件hello.c:hello函数返回参数类型(L101);
2.修改文件beauty.c:将hello函数结果进行输出(L20);
3.增加2017/10/1的客户需求到文件stupidClient.c中。
3.注释信息应保留必要的信息:
倘若你认为这一次的commit是有必要的,那么请在注释说明中说明以下必要的信息:
- 1.为什么这次修改是必要的,它解决了什么问题/它的目的是什么?
- 2.这次commit是如何解决问题/达到上述目的的?
- 3.影响的文件有哪些?
错误示例:
Commit Title:
Fix bug // 它解决了什么问题?
Commit Content:
// 这次commit是如何解决问题的?影响的文件有哪些?
<Empty>
参考示例:
Commit Title:
Fix bug #1 // 它解决了issue#1,因此这次修改是必要的
Commit Content:
// 这次commit通过...解决了问题。影响了文件src/hello.c。
1.修改文件src/hello.c:修改hello_beauty()函数的返回参数类型(L30);
2.在单元测试中增加测试test1,避免#1的重复发生。
此外,有一些commit完全没有必要,或者对于该项目毫无意义,比如:
错误示例1:小陈为了刷KPI(Key Performance Indicator,关键绩效指标),将文件A中所有的空行删除,做了一次提交,心里美滋滋的。
错误示例2:负责在Github上进行某个项目开发的小李被开除了,被迫离开了现在的公司;在离开前,她将本地仓库中所有的内容删除,并将这些修改提交到了项目中,以此宣泄心中的愤恨。
不提交没有必要、毫无意义的commit是每一个项目成员应该遵守的规范。
一些建议:
(1)个人推荐以Github的客户端,如Github Desktop为主、命令行为辅来进行commit提交,写提交信息时的效果图如下:
此外,还可以在desktop上查看历史的提交记录:
(2)在使用命令行进行提交时,通常使用git commit -m '注释信息'
来填写commit注释信息,但是-m
参数适合单行注释,对于多行的commit注释来说是不合适的。这里推荐使用git commit -v
命令,会自动跳出文本栏以供commit注释信息的编辑,其中文本的首行将作为commit的标题,剩余部分将作为补充信息。
(3)如果某次提交修改的范围非常大,即改动了非常多的文件,建议划分为多次commit,每次提交一个子模块并加以对应信息的说明;如果某次提交修改的范围较小,比如只修改了一个文件中某个变量的赋值操作,可以酌情与其他commit合并为一个commit,在注释信息中说明这一点即可。
(4)阮一峰老师写了一篇关于Github commit注释信息的博客:Commit message 和 Change log 编写指南,介绍了AngularJS团队的commit注释信息格式,这里推荐给大家。
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
拓展阅读:
三、README形式的Github文档撰写
一个规范化、详细的文档是一个优秀项目必不可少的内容。在Github上有两种撰写文档的方式,一种是"README",另一种是wiki,本节主要介绍笔者在使用README进行文档记录的一些经验,主要包括:
- 1.如何创建README文档;
- 2.使用Markdown语法记录、修改文档;
- 3.通用的README文档格式;
- 4.实验室Github科研型项目,README文档的参考示例;
- 5.现有大型商用项目README文档参考示例。
1.如何创建README文档
方法一:
在创建一个新的项目时,有一个名为"Initialize this repository with a README"的选项,勾选即可为该项目创建一个README文档:
在项目目录中,该文件是"README.md",.md
后缀表明该文件是Markdown文件,使用Markdown文本编辑语言进行文件编辑。
方法二:
在项目主页中,有一个名为"Create new file"的按钮,如图红色阴影部分所示:
点击进入创建界面,在"Name your file"一栏中,填入以.md
后缀名结尾的文件名,如"README.md":
Github默认在页面中显示使用"README.md", "readme.md", "README", "readme"作为名字的文件内容;其中在显示"README.md"和"readme.md"文档时,Github基于Markdown语法对其进行显示,比如将文件的内容:# [标题名称]
以一级标题的形式显示出来。
紧接着就可以在下方的文本框中开始文档的撰写了。此外,Github支持在线的文档视图,点击如图红色方框 "Preview"(创建文件时显示)/"Preview changes"(修改文件时显示) 所示:
即可将刚才新增/修改的内容以可视化的形式呈现:
最后,合理在commit中描述该文档,并将该文档提交到你的项目中:
方法三:
在主机的仓库中创建README文档,并提交至Github上。该方法不再具体阐释。
注:上文中创建的README文档即项目中的simple-README.md。
2.使用Markdown语法记录、修改文档
这里为读者提供了一些用于掌握基本的Markdown语法的参考资料,包括:
Github上README文档的记录、修改与普通的Markdown文档的记录、修改无异。
3.通用的README文档格式
Github官方给出了一种通用的README文档格式:
- 项目名:在人们往下浏览你的仓库之前,首先会看到你的项目名称;项目名称应在README文件的首部。
- 描述:对于接下来README内容的一个描述;一个好的描述是非常清晰、简洁、切合主题的;用于描述该项目的重要性以及作用。
- 内容表格:可选;引入内容表格的目的在于为人们提供一个快捷的导航,尤其是在README文档内容多且详细的时候。
- 安装:接着,安装教程告诉用户如何快速、正确安装你的项目;可以考虑的是,做一个gif描述安装过程,使其他人对整个过程更加清楚。
- 使用说明:下一个阶段是使用说明,用于告诉已经安装好项目的用户如何使用你的项目;该处适合增加一些项目的截屏。
- 贡献:一个大型商用项目通常有一个独立的章节,用于描述如何为这个项目作出贡献(如文件命名、编码规范等),有时可能是一个独立的描述文件;如果你有特殊的要求,详细地解释你的要求有助于其他开发者更好地为你的项目做出贡献。深入阅读:setting guidelines for repository contributors
- 荣誉:增加一个章节用于列举出项目的作者和做出贡献的开发者们。
- 许可证:加入一个章节用于描述该项目的许可证。如何选择一个合适的许可证:licensing guide,也可以参考阮一峰老师的教程:如何选择开源许可证?
4.实验室Github科研型项目,README文档的参考示例
标准语言:English。
一个实验室Github科研型项目,README文档参考示例由以下几个部分组成:
- Chapter1: 项目名称(一级标题)+项目贡献描述(内容,以点列出);
- Chapter2: 安装所需的软件依赖,贴上对应的Installation Guide链接;
- Chapter3: "Getting Start" 项目,即入门级项目,一个帮助用户快速上手的demo;
- Chapter4: README主体部分,以项目贡献点列章节,每个章节阐述项目中对应于该贡献点的文件和子模块;
- Chapter5: 相关工作,相关的论文或者Github项目,给出链接;
- Chapter6: 问题向导,当用户遇到问题时解决问题的方法,包括给出社区链接、相关issues、联系邮件地址等等;
- Chapter7: 引用的参考文献,作者信息。
5.现有大型商用项目README文档参考示例
四、参考资料
- CloudLab Coding Style Guide, George Washington University
- Github Guides
- Git 写出好的 commit message
- 写好 Git Commit 信息的 7 个建议
- Commit message 和 Change log 编写指南
- AngularJS Git Commit Message Conventions
- Documenting your projects on GitHub
- Mastering Issues
- 极简MarkDown排版介绍(How to)
- Markdown快速入门
- Mastering Markdown
- setting guidelines for repository contributors
- licensing guide
- 如何选择开源许可证?
- Composite Style Guide
- Google's C++ Style Guide
关于如何更好地使用Github的一些建议的更多相关文章
- 在用 JavaScript 工作时,我们经常和条件语句打交道,这里有5条让你写出更好/干净的条件语句的建议。
1.多重判断时使用 Array.includes 2.更少的嵌套,尽早 return 3.使用默认参数和解构 4.倾向于遍历对象而不是 Switch 语句 5.对 所有/部分 判断使用 Array.e ...
- [福大软工] Z班——个人技术博客评分
个人技术博客 作业地址 https://edu.cnblogs.com/campus/fzu/SoftwareEngineering2015/homework/1070 作业要求 个人技术博客单次作业 ...
- 如何用Github版本控制非Github库
Git的图形化客户端有很多,不同的人可能习惯用不同的客户端.本人更习惯于Github的客户端,因为上Github比较多,同步代码到Github用官方的客户端是最方便的,所以也就更习惯于使用Github ...
- 【原】Github系列之二:开源 一行代码实现多形式多动画的推送小红点WZLBadge(iOS)
更新日志 V1.2 2015.09.25 1.UITabBarItem badge is supproted; 2.Enable change badge properties when badge ...
- 版本控制简介,git使用----使用GitHub托管代码
关于版本控制: 很久以前,人们苦于对写过的代码进行版本的管理,经常过了一段时间想恢复原来写过的代码却又忘了不知道丢到哪儿去了,有的人用加上时间后缀来命名文件的方法,便于后期维护,但是这样做的麻烦也很大 ...
- Github使用指南-从新手到专家
转载自:http://www.cnblogs.com/xirongliu/p/4589834.html 个人从刚刚开始接触github,啥都不知道,不会用,不知道能够用来干什么,到现在坚持在githu ...
- iOS如何上传代码到Github
iOS如何上传代码到Github 很多iOS开发者想开源自己的代码或者demo,开源到Github是个不错的选择,那么如何上传我们的代码到Github,令所有人可以下载使用呢?这里我们的目的很明确,就 ...
- GitHub 里面有大量优秀的第三方框架
写iOS 程序的时候往往需要很多第三方框架的支持,可以大大减少工作量,讲重点放在软件本身的逻辑实现上. GitHub 里面有大量优秀的第三方框架,而且 License 对商业很友好.一下摘录一下几乎每 ...
- Visual Stuido 2015 Community 使用 GitHub 插件
微软在Visual Studio 2015产品中,深度整合了GitHub,让VS用户更方便的使用GitHub的服务. 新闻链接: Announcing the GitHub Extension for ...
随机推荐
- Nodejs进阶:服务端字符编解码&乱码处理
写在前面 在web服务端开发中,字符的编解码几乎每天都要打交道.编解码一旦处理不当,就会出现令人头疼的乱码问题. 不少从事node服务端开发的同学,由于对字符编码码相关知识了解不足,遇到问题时,经常会 ...
- 关于RequestDispatcher的原理
RequestDispatcher简介 RequestDispatcher 代表请求的派发者.它有2个动作:forward 和 include .客户端对于任何一个请求,可以根据业务逻辑需要,选择不同 ...
- 一台电脑 一起跑python2 python3
我习惯使用python2.7,命令都是使用的python和pip,这时候装了python3.4,首先到python3下修改python.exe,pythonw.exe为python3.exe,pyth ...
- 原创: rsync软件服务利用ansible实现一键化部署
---恢复内容开始--- 首先创建一个脚本文件 /server/tools/peizhi.sh cat /server/tools/peizhi.sh cat >>/etc/rsyncd ...
- Web桌面应用框架2:著名的WEB桌面应用分析
前一篇文章里,分析了包括NW.js和electron这种纯JS框架在内的几种Web桌面应用开发方式,实际上还有一种最古老的方式,那就是嵌入WebView的方式. 嵌入WebView的方式和整个程序都是 ...
- h5的video标签
在video标签中,我们可以使用属性:videoWidth & videoHeight,它获取的是video的宽度和高度(媒体本身). 虽然不能直接使用,但是可以通过计算宽高比得到 video ...
- 7_SQL Server通过代码删除数据
--通过代码方式删除数据select *from Employee --第一种删除方式,数据没了,表还在,id接着删除前的id继续加1delete from Employee where EmpId ...
- 第3阶段——内核启动分析之prepare_namespace()如何挂载根文件系统和mtd分区介绍(6)
内核启动并初始化后,最终目的是像Windows一样能启动应用程序,在windows中每个应用程序都存在C盘.D盘等,而linux中每个应用程序是存放在根文件系统里面,那么挂载根文件系统在哪里,怎么实现 ...
- 全平台轻量级 Verilog 编译器 & 仿真环境
一直苦于 modelsim 没有Mac版本,且其体量过大,在学习verilog 时不方便使用. 终于找到一组轻量级且全平台 ( Linux+Windows+macOS ) 的编译仿真工具组. Icar ...
- 团队作业4——第一次项目冲刺(Alpha版本)2st day
一.Daily Scrum Meeting照片 二.燃尽图 三.项目进展 界面 1.四个用户登录界面已经完成. 2.界面内的功能完成了一小部分. 登陆部分 1.QQ授权已经申请,还未通过. 2.通过好 ...