关于如何更好地使用Github的一些建议

时间 2019-11-24

标签关于如何更好使用 github 一些建议栏目 Git 繁體版

原文原文链接

关于如何更好地使用Github的一些建议

原文(Github repository形式): https://github.com/Wasdns/github-example-repohtml

本文记录了我对于Github使用的一些技巧，并针对如下几个方面:git

1、提交问题；
2、提交(commit)的注释信息；
3、README形式的Github文档撰写。

给出了本身的一些建议，不足之处欢迎各位指出，欢迎补充和提问：）。github

1、提交问题

在提问以前，请确认你的问题是否可以经过如下方式解决：(1)百度；(2)bing；(3)Google；(4)Stackoverflow。ubuntu

一个参考的主要提问步骤分为：ruby

(1)标题：出现bug的概要，例："在根目录下，某某文件没法找到"
(2)背景介绍(可选)：介绍你大概的目的是什么；例："为了测试数独，我作了这个实验，遇到了这个问题。"
(3)实验环境：你的系统环境、安装的依赖，选择性给出；例："个人操做系统为Ubuntu 14.04，64位。"
(4)重要：重现bug的步骤，尽可能条理清晰、简明；
(5)期待出现的行为(可选)：若是没有遇到这个bug，你但愿获得的结果是什么；
(6)结果出现的行为：较为全面的bug信息，或者错误日志，或者两者兼具；
(7)额外信息：一些附加的信息，如代码(简短的骨架，或者以站外连接的形式贴出)，或者你对于该错误的认识；
(8)礼貌用语。

错误示范：WTF the bug is?markdown

参考样例："error: HashAlgorithm.csum16: Invalid enum tag"ide

2、提交(commit)的注释信息

对于一个commit来讲，一个完备的注释信息有助于让其余人了解你的此次提交作了什么工做。例如，项目管理员对PR进行code review时须要对于该PR的每一次提交进行审核，若是每次提交的注释信息都很是简单/杂乱，那么对于code reviewer来讲是很是不友好的：他须要翻看你每一次文件的修改记录来判断你的此次提交作了什么工做。svn

一个规范的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>

拓展阅读：

3、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: 引用的参考文献，做者信息。

关于如何更好地使用Github的一些建议

关于如何更好地使用Github的一些建议

1、提交问题

2、提交(commit)的注释信息

3、README形式的Github文档撰写

1.如何建立README文档

2.使用Markdown语法记录、修改文档

3.通用的README文档格式

4.实验室Github科研型项目，README文档的参考示例

5.现有大型商用项目README文档参考示例

4、参考资料