Go项目开源规范
我们为什么一定要知道开源规范呢?
- 一是,开源项目在代码质量、代码规范、文档等方面,要比非开源项目要求更高,在项目开发中按照开源项目的要求来规范自己的项目,可以更好地驱动项目质量的提高;
- 二是,一些大公司为了不重复造轮子,会要求公司团队能够将自己的项目开源,所以提前按开源标准来驱动 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。
Go项目开源规范的更多相关文章
- Android 项目优化(一):项目代码规范优化
项目代码规范为主要包含:类,常量,变量,ID等命名规范:注释规范:分包规范:代码风格规范. 项目代码规范是软件开发过程中非常重要的优化环节. 目前的开发社区提供了很多的开发规范文档,阿里巴巴推出了&l ...
- Java Web 项目目录规范
一.项目结构 这里和其他项目区别不大,我将模板抽离出来,更容易分析和理解: 解释一下:js主要包括extends(引入第三方的js).module(项目模块自己的js).lib(引用包,这里也可以继续 ...
- C#项目代码规范
C#项目代码规范 前言 小菜就是小菜,几个人搞出来的项目,让公司大牛稍微看了下,最后送出了惨不忍睹四个字.命名各种各样,五花八门,大写英文.小写英文.大写拼音.小写拼音.英文和拼音组合.字母和特殊 ...
- adhoc-海量数据多维自助即席查询平台-mdrill项目开源啦
adhoc-海量数据多维自助即席查询平台-mdrill项目开源啦 1:mdrill是阿里妈妈-adhoc-海量数据多维自助即席查询平台下的一个子项目. 2:mdrill旨在帮助用户在几秒到几十秒的时间 ...
- 转:Java项目开发规范参考
Java项目开发规范参考 - KevinLee的博客 - 博客频道 - CSDN.NEThttp://blog.csdn.net/u011383131/article/details/51227860 ...
- LR(0)文法项目集规范族、DFA和分析表的构建实例
最近在复习编译原理,考试之前以为自己懂了,眼高手低就没去实践.结果一考试出问题了.... 学习就要脚踏实地,容不得半点模糊.凭着侥幸心理很危险的.以后要引以为戒啊. 特别写出这篇文章 :一来总结一下这 ...
- day 14 项目目录规范; time ; logging
import sys print(sys.modules) 程序一运行,解释器将里面的所有内容全部加载到内存 项目目录规范: 代码不可能全部只写在一个文件,十几万行代码,调整,修改都很不方便. 所 ...
- Idea项目注释规范设置
Idea项目注释规范设置文档 1.类注释: /** *@ClassName: ${NAME} *@Description: TODO *@Author: guohui *@Da ...
- 团队开发前端VUE项目代码规范
团队开发前端VUE项目代码规范 2018年09月22日 20:18:11 我的小英短 阅读数 1658 一.规范目的: 统一编码风格,命名规范,注释要求,在团队协作中输出可读性强,易维护,风格一致 ...
随机推荐
- Linux:find命令中
默认情况下, find 每输出一个文件名, 后面都会接着输出一个换行符 ('\n'), 因此我们看到的 find 的输出都是一行一行的: ls -l total 0 -rw-r--r-- 1 root ...
- easyhadoop 安装
ldconfig deferred processing now taking place正在处理用于 libapache2-mod-php5 的触发器... * Reloading web serv ...
- SVN终端演练-版本回退
1. 版本回退概念以及原因? 概念: 是指将代码(本地代码或者服务器代码), 回退到之前记录的某一特定版本 原因: 如果代码做错了, 想返回之前某个状态重做;2. 修改了,但未提交的情况下 ...
- 【Linux】【Basis】【RHEL】KickStart for RHEL6.8
1. 概念: 自动安装的脚本,这篇文章以RHEL6.8为例 kickstart for RHEL6.8官方教程:https://access.redhat.com/documentation/en-U ...
- .net 5 开发部署B/S程序。
现在.net 6 已经出来了,visualStudio 2022也发行预览版了. 自 .net5 发布,.net core 与.net framework 已经走向统一.确实越来越好用了. 现在.ne ...
- Mysql资料 视图
目录 一.简介 二.例子 三.好处 四.工作机制 一.简介 视图是数据库中的一个虚拟的表是一个虚拟表,其内容由查询定义.同真实的表一样,视图包含一系列带有名称的列和行数据. 但是,视图并不在数据库中以 ...
- GoLang设计模式17 - 访客模式
说明 访客模式是一种行为型设计模式.通过访客模式可以为struct添加方法而不需要对其做任何调整. 来看一个例子,假如我们需要维护一个对如下形状执行操作的库: 方形(Square) 圆形(Circle ...
- 小迪安全 Web安全 基础入门 第六天 - 信息打点-Web架构篇&域名&语言&中间件&数据库&系统&源码获取
一 . Web架构 语言.常用的Web开发语言有PHP,Java,Python,JavaScript,.net等.具体可参考w3school的介绍. 中间件. (1)常见的Web服务器中间件:IIS. ...
- nodejs+koa+uniapp实现微信小程序登陆获取用户手机号及openId
nodejs+koa+uniapp实现微信小程序登陆获取用户手机号及openId 前言: 我准备用nodejs+koa+uniapp实现一款餐饮点单小程序,以及nodejs+koa+vue实现后端管理 ...
- 误入 GitHub 游戏区,意外地收获颇丰
这天中午,我和往常一样就着美食视频吃完午饭,然后起身泡了一杯"高沫". 我闻着茶香享受着午后的阳光,慵懒地坐在工位上习惯性的打开 GitHub 游荡,酝酿着睡意. 误打误撞,我来到 ...