更新时间：2020-04-04

目标

  • 杜绝人员单点依赖风险（杜绝项目依赖特定个人，杜绝只有某个人才知道某个项目的关键点）
  • 降低代码失控风险（降低代码千人千面情况）
  • 快速入手（拥有开发能力的个人，可以短时间内，无需指点的自助进入开发状态）
  • 代码整洁（让拥有代码洁癖的人，参与旧项目也有宾至如归的感觉）

原则

  • code-repo-has-max-context 代码仓库拥有最大的上下文信息。该原则指，一个项目的全部信息（包括但不限于：PRD、部署信息、设计文档、测试、开发入门手册）可以通过代码仓库在明确的有限次跳后可以到达，不允许出现代码仓库无法触达信息孤岛
  • develop-docs-all-in-code-repo 所有与开发相关的文档维护在代码仓库中（包括但不限于：系统设计文档、技术分享、开发环境搭建指南、开发规范）
  • specification-by-tool-constraint 所有实施的规范必须通过工具进行约束，口头规范约束是无效的
  • simple-local-run 代码仓库必须是可以在本地环境（个人电脑）根据文档在简单的配置后可运行的
  • use-newest-lts-version 编程语言和依赖库使用最新的 lts 版本（或 stable），在新版本兼容性不足时或者生态受限时可以使用 latest - 1 版本
  • not-dependent-specific-env 不依赖特定环境，所有依赖均可已通过 包管理工具（如 apt、mvn、pip）等安装；针对特定的没有被托管在包管理工具的依赖，必须放置与代码仓库中

开发环境规范

  • 保证项目在 Mac 和 Linux 环境下可以正常开发，Windows 环境不考虑
  • 不强制要求使用特定集成开发环境
  • 不强制依赖某集成开发环境的特定功能
  • 强制依赖cli环境的开发工具链

通用文件目录

  • .gitignore
  • **/.gitkeep
  • cli/
  • docs/
  • README.md
  • .editorconfig

git

约定使用 git 做代码版本管理工具，必须包含如下文件

  • .gitignore 忽略文件
  • **/.gitkeep 空目录建议添加一个 .gitkeep 文件以保证目录也被提交到 git 仓库中

cli

Shell 脚本，需要托管的二进制文件，等可执行文件放置于 cli 目录下，其目录结构如下

  • cli/
    • cli/*.sh Shell 脚本
    • cli/lib/ Shell 脚本依赖的库，比如 jar 包等

docs

项目的各种文档，强制使用 markdown 格式进行编写，文档必须放在 markdown 目录下的二级目录下，命名格式为 %d%d.文件名.md，图片放置于 docs/asserts/images 目录下，一个例子如下：

  • docs/
    • docs/asserts/images
    • docs/01.环境搭建/01.通用环境.md
    • docs/01.环境搭建/02.VSCode开发环境.md

README.md

项目梗概，同时可以包含 get started，非常重要，相当于项目主页

.editorconfig 等其他配置文件

  • .editorconfig 是一种跨编辑器的通用文件格式配置文件，支持大多数主流编辑器和集成开发环境

分支管理与Devops

可以根据项目复杂度和人员规模进行选择，本规范采用单主干模式

  • 一个主干分支
  • 多个其他分支

准入流程（开发）

  • 其他分支向 主干分支 提交 merge request 请求（下文简称 mr）
  • （可选）准入工作流 拦截 该 mr，进入准入工作流
    • 进行代码规范检查
    • 单元测试
    • 功能测试
    • 以上各个阶段均成功后，进入下一阶段
  • 邀请 Reviewer 进行 Review 和 合并

主干流程（上线）

  • Merge 成功后进入 该流程（可选的每日定时集成）
    • 项目编译
    • 制作镜像
    • 基准测试
    • 人工卡点
    • K8S上线

P.S.

  • 准入工作流需要在本地的 git hook 脚本 pre_commit 中进行配置