我们为什么一定要知道开源规范呢？
- 一是，开源项目在代码质量、代码规范、文档等方面，要比非开源项目要求更高，在项目开发中按照开源项目的要求来规范自己的项目，可以更好地驱动项目质量的提高；
- 二是，一些大公司为了不重复造轮子，会要求公司团队能够将自己的项目开源，所以提前按开源标准来驱动 Go 项目开发，也会为我们日后代码开源省去不少麻烦。
开源协议
在上图中，右边的协议比左边的协议宽松，在选择时，你可以根据菱形框中的选择项从上到下进行选择。
开源规范具有哪些特点？
- 第一，开源项目，应该有一个高的单元覆盖率。
- 第二，要确保整个代码库和提交记录中，不能出现内部 IP、内部域名、密码、密钥这类信息。
- 第三，当我们的开源项目被别的开发者提交 pull request、issue、评论时，要及时处理，一方面可以确保项目不断被更新，另一方面也可以激发其他开发者贡献代码的积极性。
文档规范
项目中需要三类文档：README文档、项目文档和API接口文档。
README规范
# 项目名称
<!-- 写一段简短的话描述项目 -->
## 功能特性
<!-- 描述该项目的核心功能点 -->
## 软件架构（可选）
<!-- 可以描述一下项目的架构 -->
## 快速开始
### 依赖检查
<!-- 描述该项目的依赖，比如依赖的包、工具或者其他任何依赖项 -->
### 构建
<!-- 描述如何构建该项目 -->
### 运行
<!-- 描述如何运行该项目 -->
## 使用指南
<!-- 描述如何使用该项目 -->
## 如何贡献
<!-- 告诉其他开发者如果给该项目贡献源码 -->
## 社区(可选)
<!-- 如果有需要可以介绍一些社区相关的内容 -->
## 关于作者
<!-- 这里写上项目作者 -->
## 谁在用(可选)
<!-- 可以列出使用本项目的其他有影响力的项目，算是给项目打个广告吧 -->
## 许可证
<!-- 这里链接上该项目的开源许可证 -->
项目文档规范
- 项目文档通常集中放到/docs目录下
- 开发文档：用来说明该项目的开发流程，比如如何搭建开发环境、构建二进制文件、测试、部署等。
- 用户文档：比如，API文档，SDK文档，安装文档，功能介绍文档、最佳实践、操作指南、常见问题等。
示例：
docs
├── devel # 开发文档，可以提前规划好，英文版文档和中文版文档
│ ├── en-US/ # 英文版文档，可以根据需要组织文件结构
│ └── zh-CN # 中文版文档，可以根据需要组织文件结构
│ └── development.md # 开发手册，可以说明如何编译、构建、运行项目
├── guide # 用户文档
│ ├── en-US/ # 英文版文档，可以根据需要组织文件结构
│ └── zh-CN # 中文版文档，可以根据需要组织文件结构
│ ├── api/ # API文档
│ ├── best-practice # 最佳实践，存放一些比较重要的实践文章
│ │ └── authorization.md
│ ├── faq # 常见问题
│ │ ├── iam-apiserver
│ │ └── installation
│ ├── installation # 安装文档
│ │ └── installation.md
│ ├── introduction/ # 产品介绍文档
│ ├── operation-guide # 操作指南，里面可以根据RESTful资源再划分为更细的子目录，用来存放系统核心/全部功能的操作手册
│ │ ├── policy.md
│ │ ├── secret.md
│ │ └── user.md
│ ├── quickstart # 快速入门
│ │ └── quickstart.md
│ ├── README.md # 用户文档入口文件
│ └── sdk # SDK文档
│ └── golang.md
└── images # 图片存放目录
└── 部署架构v1.png
API接口文档规范
接口文档又称为 API 文档，一般由后台开发人员编写，用来描述组件提供的 API 接口，以及如何调用这些 API 接口。
接口文档有四种编写方式，包括编写 Word 格式文档、借助工具编写、通过注释生成和编写 Markdown 格式文档。具体的实现方式见下表：
推荐使用Markdown格式的文档，原因如下：
- 相比通过注释生成的方式，编写 Markdown 格式的接口文档，能表达更丰富的内容和格式，不需要在代码中添加大量注释。
- 相比 Word 格式的文档，Markdown 格式文档占用的空间更小，能够跟随代码仓库一起发布，方便 API 文档的分发和查找。
- 相比在线 API 文档编写工具，Markdown 格式的文档免去了第三方平台依赖和网络的限制。
- 接口描述：描述接口实现了什么功能。
- 请求方法：接口的请求方法，格式为 HTTP 方法 请求路径，例如 POST /v1/users。在 通用说明中的请求方法部分，会说明接口的请求协议和请求地址。
- 输入参数：接口的输入字段，它又分为 Header 参数、Query 参数、Body 参数、Path 参数。每个字段通过：参数名称、必选、类型 和 描述 4 个属性来描述。如果参数有限制或者默认值，可以在描述部分注明。
- 输出参数：接口的返回字段，每个字段通过 参数名称、类型 和 描述 3 个属性来描述。
- 请求示例：一个真实的 API 接口请求和返回示例。
版本规范
- 语义化版本格式为：主版本号.次版本号.修订号（X.Y.Z），其中 X、Y 和 Z 为非负的整数，且禁止在数字前方补零。
- 版本号可按以下规则递增：
- 主版本号（MAJOR）：当做了不兼容的 API 修改。
- 次版本号（MINOR）：当做了向下兼容的功能性新增及修改。这里有个不成文的约定需要你注意，偶数为稳定版本，奇数为开发版本。
- 修订号（PATCH）：当做了向下兼容的问题修正。
例如，v1.2.3 是一个语义化版本号，版本号中每个数字的具体含义见下图：
先行版本号（Pre-release）和版本编译元数据，作为延伸加到了主版本号.次版本号.修订号的后面，格式为 X.Y.Z[-先行版本号][+版本编译元数据]，如下图所示：
先行版本号意味着，该版本不稳定，可能存在兼容性问题，格式为：X.Y.Z-[一连串以句点分隔的标识符] ，比如下面这几个例子：
1.0.0-alpha
1.0.0-alpha.1
1.0.0-0.3.7
1.0.0-x.7.z.92
编译版本号，一般是编译器在编译过程中自动生成的，我们只定义其格式，并不进行人为控制。下面是一些编译版本号的示例：
1.0.0-alpha+001
1.0.0+20130313144700
1.0.0-beta+exp.sha.5114f85
注意，先行版本号和编译版本号只能是字母、数字，且不可以有空格。
语义化版本控制规范
- 标记版本号的软件发行后，禁止改变该版本软件的内容，任何修改都必须以新版本发行。
- 主版本号为零（0.y.z）的软件处于开发初始阶段，一切都可能随时被改变，这样的公共 API 不应该被视为稳定版。1.0.0 的版本号被界定为第一个稳定版本，之后的所有版本号更新都基于该版本进行修改。
- 修订号 Z（x.y.Z | x > 0）必须在只做了向下兼容的修正时才递增，这里的修正其实就是 Bug 修复。
- 次版本号 Y（x.Y.z | x > 0）必须在有向下兼容的新功能出现时递增，在任何公共 API 的功能被标记为弃用时也必须递增，当有改进时也可以递增。其中可以包括修订级别的改变。每当次版本号递增时，修订号必须归零。
- 主版本号 X（X.y.z | X > 0）必须在有任何不兼容的修改被加入公共 API 时递增。其中可以包括次版本号及修订级别的改变。每当主版本号递增时，次版本号和修订号必须归零。
如何确定版本号？
- 第一，在实际开发的时候，我建议你使用 0.1.0 作为第一个开发版本号，并在后续的每次发行时递增次版本号。
- 第二，当我们的版本是一个稳定的版本，并且第一次对外发布时，版本号可以定为 1.0.0。
- 第三，当我们严格按照 Angular commit message 规范提交代码时，版本号可以这么来确定：
- fix 类型的 commit 可以将修订号 +1。
- feat 类型的 commit 可以将次版本号 +1。
- 带有 BREAKING CHANGE 的 commit 可以将主版本号 +1。