Go Engineering - Specification - Open Source + Document + Version
规范
分类 | 规范 |
---|---|
非编码类规范 | 开源规范 |
文档规范 | |
版本规范 | |
提交规范 | |
发布规范 | |
编码类规范 | 目录规范 |
代码规范 | |
接口规范 | |
日志规范 | |
错误码规范 |
开源规范
开源协议
Apache 是对商业应用友好的协议,大公司的开源项目通常会采用 Apache 2.0 开源协议
开源项目
- 较高的单元覆盖率
- 代码库中不能包含敏感信息
- 及时处理 PR、ISSUE 等
- 持续更新和 Bug Fix
文档规范
文档属于软件交付的一个重要组成部分
README
1 | # 项目名称 |
项目文档
1 | docs |
API 文档
编写方式
Markdown 为最优选择(个人)
组成
- 介绍文档
- 变更历史文档
- 通用说明
- 数据结构说明
- 错误码描述
- API 接口文档
- 接口描述
- 请求方法:POST /v1/users
- 输入参数:Header、Query、Body、Path
- 输出参数
- 请求示例
Markdown | Desc |
---|---|
README.md | 介绍文档 |
CHANGELOG.md | 变更历史文档 |
generic.md | 通用的请求参数、返回参数、认证方法和请求方法等 |
struct.md | 数据结构文档,会在 user.md、secret.md、policy.md 中被引用 |
user.md secret.md policy.md |
API 接口文档 相同 REST 资源的接口会放在同一个文件中,并以 REST 资源命名文档文件名 |
error_code.md | 错误码描述,通常由程序自动生成 |
版本规范
语义化版本规范
语义化版本规范:SemVer,Semantic Versioning,
- 主版本号.次版本号.修订号(X.Y.Z):X、Y、Z 为非负整数,禁止在数字前面补零
- 主版本号(MAJOR):做了不兼容的 API 修改
- 次版本号(MINOR):做了向下兼容的功能性新增和修改,偶数为稳定版本,奇数为开发版本
- 修订号(PATCH):做了向下兼容的 Bug Fix
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
- 先行版本号和编译版本号,只能是字母+数字
- 先行版本号:该版本不稳定,可能存在兼容性问题,格式为
核心规范
- 标记版本号的软件发行后,禁止改变该版本软件的内容,任何修改都必须以新版本发行
- 主版本号为零的软件处于开发初始阶段,公共 API 不稳定,第一个稳定版本为 1.0.0
- 修订号 Z(x.y.Z | x > 0)必须在做了向下兼容的 Bug Fix 时才递增
- 次版本号 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
All articles in this blog are licensed under CC BY-NC-SA 4.0 unless stating additionally.