我们为什么一定要知道开源规范呢?

  • 一是,开源项目在代码质量、代码规范、文档等方面,要比非开源项目要求更高,在项目开发中按照开源项目的要求来规范自己的项目,可以更好地驱动项目质量的提高;
  • 二是,一些大公司为了不重复造轮子,会要求公司团队能够将自己的项目开源,所以提前按开源标准来驱动 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项目开源规范的更多相关文章

  1. Android 项目优化(一):项目代码规范优化

    项目代码规范为主要包含:类,常量,变量,ID等命名规范:注释规范:分包规范:代码风格规范. 项目代码规范是软件开发过程中非常重要的优化环节. 目前的开发社区提供了很多的开发规范文档,阿里巴巴推出了&l ...

  2. Java Web 项目目录规范

    一.项目结构 这里和其他项目区别不大,我将模板抽离出来,更容易分析和理解: 解释一下:js主要包括extends(引入第三方的js).module(项目模块自己的js).lib(引用包,这里也可以继续 ...

  3. C#项目代码规范

    C#项目代码规范   前言 小菜就是小菜,几个人搞出来的项目,让公司大牛稍微看了下,最后送出了惨不忍睹四个字.命名各种各样,五花八门,大写英文.小写英文.大写拼音.小写拼音.英文和拼音组合.字母和特殊 ...

  4. adhoc-海量数据多维自助即席查询平台-mdrill项目开源啦

    adhoc-海量数据多维自助即席查询平台-mdrill项目开源啦 1:mdrill是阿里妈妈-adhoc-海量数据多维自助即席查询平台下的一个子项目. 2:mdrill旨在帮助用户在几秒到几十秒的时间 ...

  5. 转:Java项目开发规范参考

    Java项目开发规范参考 - KevinLee的博客 - 博客频道 - CSDN.NEThttp://blog.csdn.net/u011383131/article/details/51227860 ...

  6. LR(0)文法项目集规范族、DFA和分析表的构建实例

    最近在复习编译原理,考试之前以为自己懂了,眼高手低就没去实践.结果一考试出问题了.... 学习就要脚踏实地,容不得半点模糊.凭着侥幸心理很危险的.以后要引以为戒啊. 特别写出这篇文章 :一来总结一下这 ...

  7. day 14 项目目录规范; time ; logging

    import   sys print(sys.modules) 程序一运行,解释器将里面的所有内容全部加载到内存 项目目录规范: 代码不可能全部只写在一个文件,十几万行代码,调整,修改都很不方便. 所 ...

  8. Idea项目注释规范设置

    Idea项目注释规范设置文档 1.类注释: /**    *@ClassName: ${NAME}    *@Description: TODO    *@Author: guohui    *@Da ...

  9. 团队开发前端VUE项目代码规范

    团队开发前端VUE项目代码规范 2018年09月22日 20:18:11 我的小英短 阅读数 1658   一.规范目的: 统一编码风格,命名规范,注释要求,在团队协作中输出可读性强,易维护,风格一致 ...

随机推荐

  1. Linux:find命令中

    默认情况下, find 每输出一个文件名, 后面都会接着输出一个换行符 ('\n'), 因此我们看到的 find 的输出都是一行一行的: ls -l total 0 -rw-r--r-- 1 root ...

  2. easyhadoop 安装

    ldconfig deferred processing now taking place正在处理用于 libapache2-mod-php5 的触发器... * Reloading web serv ...

  3. SVN终端演练-版本回退

    1. 版本回退概念以及原因?    概念: 是指将代码(本地代码或者服务器代码), 回退到之前记录的某一特定版本    原因: 如果代码做错了, 想返回之前某个状态重做;2. 修改了,但未提交的情况下 ...

  4. 【Linux】【Basis】【RHEL】KickStart for RHEL6.8

    1. 概念: 自动安装的脚本,这篇文章以RHEL6.8为例 kickstart for RHEL6.8官方教程:https://access.redhat.com/documentation/en-U ...

  5. .net 5 开发部署B/S程序。

    现在.net 6 已经出来了,visualStudio 2022也发行预览版了. 自 .net5 发布,.net core 与.net framework 已经走向统一.确实越来越好用了. 现在.ne ...

  6. Mysql资料 视图

    目录 一.简介 二.例子 三.好处 四.工作机制 一.简介 视图是数据库中的一个虚拟的表是一个虚拟表,其内容由查询定义.同真实的表一样,视图包含一系列带有名称的列和行数据. 但是,视图并不在数据库中以 ...

  7. GoLang设计模式17 - 访客模式

    说明 访客模式是一种行为型设计模式.通过访客模式可以为struct添加方法而不需要对其做任何调整. 来看一个例子,假如我们需要维护一个对如下形状执行操作的库: 方形(Square) 圆形(Circle ...

  8. 小迪安全 Web安全 基础入门 第六天 - 信息打点-Web架构篇&域名&语言&中间件&数据库&系统&源码获取

    一 . Web架构 语言.常用的Web开发语言有PHP,Java,Python,JavaScript,.net等.具体可参考w3school的介绍. 中间件. (1)常见的Web服务器中间件:IIS. ...

  9. nodejs+koa+uniapp实现微信小程序登陆获取用户手机号及openId

    nodejs+koa+uniapp实现微信小程序登陆获取用户手机号及openId 前言: 我准备用nodejs+koa+uniapp实现一款餐饮点单小程序,以及nodejs+koa+vue实现后端管理 ...

  10. 误入 GitHub 游戏区,意外地收获颇丰

    这天中午,我和往常一样就着美食视频吃完午饭,然后起身泡了一杯"高沫". 我闻着茶香享受着午后的阳光,慵懒地坐在工位上习惯性的打开 GitHub 游荡,酝酿着睡意. 误打误撞,我来到 ...