插件管理规范
文档版本：R2.0
1. 概要
1.1 背景
激光行业插件比较多，目前分为通用插件、平面专用插件、管切专用插件，在这些插件基础上，又有各类分支，造成插件代码分支管理难度增加，导致出现代码合并错误，忘记合并分支问题；没有统一的规范，新员工入职之后无章可循，只能自由发挥，进一步加剧分支混乱现象。代码分支的混乱最终体现在软件质量上。
另一方面，插件包版本号不规范，也造成了沟通成本的上升；本因从版本号就能传递的信息（是否兼容、Bug 修复等），必须要通过查代码、问开发人员才能获取，直接造成工作效率低下。
1.2 目的
- 降低代码维护难度
- 规范分支流程
- 规范插件包命名
1.3 用语
| 序号 | 用语 | 描述 |
|---|---|---|
| 1 | 插件 | |
| 2 | 插件包 | 插件编译、打包的产物；给集成项目使用。 |
| 3 | 集成项目 | |
| 4 | 软件 | 集成项目编译、打包出的产物；可销售的软件产品。 |
| 5 | 主动维护 | 由维宏主动发现 bug，解决 bug，发布 Fix 软件或补丁包的过程。 |
| 6 | 被动维护 | 在软件停止主动维护后，客户反馈有严重 bug 时修复 bug 的过程。 |
| 7 | 软件生命周期 | 软件的某个版本发布后到停止主动维护的时间段。 对于 Release 版本，生命周期为发布之日起到下一 Release 版本发布时截止； 对于 Beta 版本不主动维护。 |
| 8 | 插件生命周期 | 插件版本发布后到所有带这个版本的软件生命周期终止时的这个时间段。 |
2. 版本管理
2.1 插件版本
- 版本号规则： p.snn.f.rf[-suffix]， eg： 1.100.0.0-12345-alpha1 （参考 Phoenix 组件版本管理规则）
- 版本号升级规则：
| 序号 | 区段 | 说明 |
|---|---|---|
| 1 | p | 主版本号，必填，从 1 开始，无上限 |
| 2 | s | 子版本号，必填，从 1 开始到 9 |
| 3 | nn | 子版本序号，必填，从 00 开始到 99 |
| 4 | f | beta 修订版本号，必填，从 0~99：分支修订版本号 |
| 5 | rf | Fix 修订版本号，必填，从 0~99；Beta 分支发出来的版本，rf 都是 0 |
| 6 | suffix | 先行版本号，可选，由工作项 id 、后缀和序号组成，序号从 1 开始， eg： -12345-alpha1 |
- 各分段更新时机
- P 段，插件有重大更新时触发
- 对外接口有重大变化， eg：吹气重构，开关气改用子程序接口操作；
- 插件入口有重大变化， eg：管顶料重构，功能配置从 NcConfig 挪到平台配置工具；
- 插件功能表现有重大变化， eg：
- s 段，插件正式发布新功能，不保证向下兼容（包括参数、接口和功能表现）
- nn 段，插件小规模增强，保证向下兼容（包括参数、接口和功能表现）
- f.rf 段，修复插件 bug，不包含任何新功能或功能增强（即不带 Task）
- suffix 段，在工作项迭代开发过程中存在，正式版本禁止带后缀
- P 段，插件有重大更新时触发
2.2 插件包路径
| 序号 | 目录名 | 路径 | 规则 |
|---|---|---|---|
| 1 | 本地 | 开发人员本地 Public 或其他路径 | 1. 只能用于自测 2. 带先行版本后缀 |
| 2 | Public 目录 | $/Laser/_Public | 1. 可以是未经过测试的版本 2. 多人协同开发使用 3. 带先行版本后缀 |
| 3 | 包服务器 | http://phoenix.weihong.com:8088/feeds/Laser | 1. 必须是测试通过的 2. 不带先行版本后缀 |
3. 代码分支管理
3.1 分支目录
| 序号 | 目录名 | 描述 | 备注 |
|---|---|---|---|
| 1 | Beta | 主分支目录： 1. 测试通过后才允许提交到此目录 2. 一个插件在 Beta 目录仅有一个分支 3. 签入此目录代码必须通过代码评审 |
重点管理 |
| 2 | Dev | 开发分支目录： 1. 开发工作项时从Beta分支过来，测试验收通过后合并到 Beta 并删除 Dev 下分支 2. 多人合作开分支 3. 一个插件在本目录可以有多个分支 |
|
| 3 | Fix | 修复Bug分支目录： 1. 在修复外部反馈 bug 时从 Beta 分支出来，停止主动维护后删除 2. 测试通过后才允许提交到此目录 3. 签入此目录代码必须通过代码评审 4. 一个插件在本目录可以有多个分支 |
重点管理 |
分支示意图（插件）
3.2 插件分支管理
3.2.1 新建插件
- 在 Dev 下新建插件；
- 开发功能，开发迭代过程插件包，版本号为 1.100.0.0-Task ID-alphaN，放置路径：本地 或 Public 目录
- 测试验收通过后，代码提交到 Beta，同时删除 Dev 下代码；
- 给 Beta 下本次提交的变更集打 Tag【插件名-1.100.0.0】；
- 编译正式版插件包，版本号为 1.100.0.0，上传到包服务器；
- 合并功能到 Beta 目录下其它集成项目分支。
3.2.2 增加功能插件
- 从 Beta 下分支到 Dev （加上分支时 Beta 下版本号【1.101.1.0】），此处允许保留搁置集开发的方式，但必须是测试通过才能发行 ；
- 开发迭代，过程中版本号带后缀【1.101.1.0-Task ID-alphaN】；
- 开发过程，最终测试版本需要将 Beta 下最新代码合并到 Dev，并解决冲突发出测试版本；
- 测试验收通过后，代码合并到 Beta，同时删除 Dev 下代码；
- 评估修改范围，按版本号规则确定版本号（假设本次修改确定版本号【1.200.0.0】）；
- 编译正式版插件包，版本号为【1.200.0.0】；
- 给 Beta 下本次提交的变更集打 Tag【插件名-1.200.0.0】；
- 合并功能到 Beta 目录下其它集成项目分支。
3.2.3 修复 Bug
- 确定反馈软件对应的插件版本，如果使用的是 Beta 分支下最新版本（如：【1.200.0.0】），在 Beta 下修复；
- 如果使用的旧版本插件（假设使用的插件版本号【1.101.0.0】）；找到 Beta 下【插件名-1.101.0.0】的 Tag，在 Fix 目录创建分支【插件名-1.101】；
- 在 Fix 下修复 bug，搁置集方式开发；
- 测试验收通过后，发出版本号为【1.101.0.1】的插件包；
- 合并功能到 Main 下正式发行的集成项目分支；Beta 下也存在问题，则 Beta 分支也需要修改。
3.3 抢版本号问题
- 多人合作开发一个 Task：统一规划工作，由主导人负责管理分支、代码合并、确定版本号；
- 多人同时分别做多个 Task：确定 Task 交付节奏，统一规划版本后当做一个（都是兼容修改）或两个（有不兼容修改）大 Task 开发，参考第一条；
- 多人同时修复多个 Bug：参考2；
- 厂商定制问题：某厂商提出的新需求，初步评估为通用功能，但是现场要得很急。这种情况考虑插件开一个定制版本，先解决这一家客户的问题，做完后也不合其它集成项目，之后再详细评估此功能是否纳入主分支和如何做到主分支的问题。
修改记录
| 序号 | 版本 | 修订人 | 日期 | 描述 |
|---|---|---|---|---|
| 1 | R0.1 | 陈百旺 | 2021/6/30 | 初始草案 |
| 2 | R1 | 唐涛 | 2021/7/2 | 1. 修改分支管理示意图 2. 修改 Fix 目录分支规则 3. 增加 Beta、Fix 下分支的搁置集开发方式 4. 3.2.3 Bug 处理流程修改 5. 增加插件包路径 |
| 3 | R2 | 唐涛 | 2021/8/31 | 1. 插件版本号 f.f 改为 f.r 定义 Beta/Release 分支下插件包修复 bug 修改的字段 |