Sailing 之 版本升级规范

Sailing

总体来说, 目前Sailing体系下分为框架, 产品, 项目三大版块.

• 框架: 特指framework, designer和domain. framework提供了元数据驱动的开发模式, 以及支持此开发模式的工具集; domain则在framework的基础上提供了适合供应链管理领域的一系列业务抽象; designer为以上两者的可视化建模平台.
• 产品: 基于框架建模/开发得到的标准版应用, 目前主要为ERP6.0, 预警平台, 大屏, 微信小程序. 以下内容涉及的产品主要是指ERP6.0.
• 项目: 从标准产品派生而来的客户交付版本. 允许定制化, 方便定制化还将是我们的市场优势.

三个板块各有其作用, 且都出现了不同程度的市场需求. 因此内对内外都有必要整理一下各方面的操作办法.

需求来源

框架

框架的主要作用为内部的生产力工具, 其次也作为可以对外销售的一套产品. 其需求来源为:
- 产品及项目开发的反馈: 作为生产力工具, 切实提高生产力是第一要务, 一线的反馈由为重要.
- 重构: 有些需求是非功能性的, 比如出于框架运行性能, 扩展性, 可维护性, 可用性, 市场销售策略等方面的考虑, 需要对框架进行升级改造. 这些项目经正式立项.

产品

总体来说, 产品需要按照此自身特点来保持升级节奏, 升级的需求来源包括项目反馈, 市场反馈, 自研完善.
- 项目反馈: 项目进行到尾声后, 组织项目总结会, 分析该项目中的亮点, 难点. 并由产品组结合其他项目类似需求以及已有产品特点, 形成产品升级方案. 现阶段, 项目反馈是产品的主要需求来源.
- 市场反馈: 根据市场综合情况收集到的需求, 经正式立项. 这类需求往往是在需要开一条新产品线的时候会出现.
- 自研完善: 产品不断积累思考后得到的优化方案, 经正式立项. 此类需求往往是在应用模块复杂到了一定程度, 需要重构提高可配置性, 可维护性的时候会出现.

项目

项目的需求完全来自客户. 项目是公司收入的主要来源, 为了保持项目考核的纯粹性, 项目需求完全来源于项目.

版本管理

整个Sailing产品体系总体上服务于项目, 因此版本管理相对复杂, 需要兼顾框架, 产品和项目. Sailing早期有过兼顾产品和项目的版本化方案, 方案试图将项目和产品的所有调整纳入同一套版本中来调整, 以此来达到项目个性化修改后, 还能实现产品升级的目的. 但文中方案过于理想化, 不具备可操作性. 此外还探讨过如何保持产品元数据在项目中的兼容性的方案, 但难度很大, 至今还没有精力实现.

目前实践下来, 现阶段, 框架, 产品, 项目三者之间保持以下关系是比较恰当的:

• 框架(framework, domain)由公司统一维护, 产品和项目都不允许修改. 产品和项目直接引用框架库包, 框架需确保平稳升级, 平稳升级的含义是以下几种之一:
  
  • 框架升级后, 不包含任何break changes, 框架使用方无需任何调整;
  • 框架升级后, 包含break changes, 但框架内在机制可以自动迁移变化点;
  • 框架升级后, 包含break changes, 但框架(或附加工具包)提供了手动迁移工具;
• 产品根据自身的节奏升级, 且因为完全产品销售的概率很小, 至今未碰到过, 因此仅考虑有限的向下兼容.
• 项目从最近一个稳定版本的产品分支而来, 原则上产品之后的升级不在应用到项目, 项目也不在直接合并回产品. 也就是说, 项目一旦从产品分支出去之后就保持版本控制技术上的独立, 以此减少版本控制复杂度, 增加可操作性, 提高项目专注度. 此外, 项目中存在一些依赖层次较高的且完全没有二开过的功能, 这部分功能其实是可以得到产品升级的, 此种场景下case by case分析.

下面具体说明各个部分的版本控制策略.

框架程序库

框架以程序库的形式发布到包管理器(maven, npm)中, 包本身包含版本号信息, 包中的各个模块也包含版本号信息, 两者用途不同.

模块版本号(需调整)

模块版本号用于管理模块级别的升级发布. 分两段: major.minor

• major: 主版本号. 凡是发生了外在功能变化的发布, 主版本号需要递增. 外在功能变化包括:
  
  • 接口新增, 删除, 废弃, 变化
  • webapi新增, 删除, 废弃, 变化
  • 服务或者接口实现的语义发生了变化
• minor: 子版本号. 同一个主版本下, 每次发布子版本号都要递增. 由于外在功能变化需要递增主版本号, 因此引起子版本号变化的原因主要为:
  
  • bug修复
  • 局部(不改变接口)的实现重构

major版本号发生变更后, 需要一定的机制触发自动版本迁移逻辑. 如果确实很难做到自动迁移, 那么必须提供工具协助手工迁移, 迁移工具必须进行版本校验, license校验

包版本号(缺)

包版本号用于区分包管理器中的多个发布版本. 分三段: record.major.minor

• record: 无技术层面的含义, 和产品证书或软著保持一致. 对外宣传和商务文件上仅标识这个版本号.
• major, minor: 定义与模块版本号相同, 只不过范围是整个包中的所有模块.

元数据

元数据架构版本

原则上, 元数据架构属于某个模块, 元数据架构的调整必然引起模块的调整, 因此, 元数据架构版本号和模板版本号保持一致, 定义和版本迁移方法也一致. 但在一个模块包含多个元数据的场景中, 这种控制方法过于粗放, 因此, 元数据架构版本独立于模板版本. 版本号分两段: major.minor

• major: 主版本号. 元数据架构定义发生变化的时候, 主版本号需要递增. 架构变化包括:
  
  • 字段新增, 删除
  • 字段名称
  • 字段类型变化
  • 字段语义变化

• minor: 子版本号. 每次发布不改变架构的元数据变更时, 子版本号都要递增. 不改变架构的变更包括:

  • 修改元数据验证项
  • 修改元数据默认值

• ? 元数据迁移过程中, 需要参考其他元数据

元数据版本(缺)

对元数据内容的修改也应该版本化, 具体体现为任何修改都应带有时间戳和设计器用户名.

• ? 元数据验证时, 需要获取业务数据

应用模块

应用模块主要就是实体定义, 自定义的函数, 服务等硬编码的部分, 这部分的版本管理办法和模块版本相同. 区别在于产品和不同项目之间是版本连续性是独立的, 换句话说, 不同项目中的同样版本不具有可替代性.

此外, 应用模块也可以定义自己的元数据. 如果这么做了, 元数据版本管理同上述元数据章节.

发布规范

所有的程序发布, 特别是框架和项目, 影响面十分的广, 为了减少发布过程本身的问题, 所有的发布都需要专人负责.
暂定:
- 框架前端, VIP; 框架后端, 大师;
- 产品: 谦哥;
- 项目: 各项目中指定人员;

framework, domain发布流程

1. 开发完成后, 修改对应包说明文件的版本号, 以及本版本的发布日志(release note);
2. 打包发布到对应的包管理服务器中, 技术允许的情况下, 上传打包文件以及源码和调试信息文件.
3. 如果改的是framework, 且domain需要使用新framework, 则还需对domain执行步骤1,2.
4. 将release note发到指定公告板中. 暂时发布到Sailing群公告中, 后续迁移到新任务系统;
5. 在Sailing群中提醒各方有新版本.

产品发布规范(缺)

目前产品的开发缺乏连续性, 相邻版本的差异巨大, 后续产品升级需要考虑原产品特性.

项目发布SOP(暂定)

方案A

项目启动后, 在适当的时候从产品主干fork出项目. 项目由两个分支组成:
- 项目主分支. 项目分支之后建立的第一个分支.
- 线上分支. 对应线上修改元数据的分支.

1. 日常离线修改的元数据和代码, 提交到项目主分支.
2. 日常线上修改的内容, 修改好之后提交到线上分支.
3. 发布前, 确保客户环境中的线上分支都push了; 随后在开发环境中pull线上分支, 并将线上分支合并到项目主分支, 如发生冲突解决之.
4. 合并成功后, 将项目主分支合并回在线分支, 由于上一步中已经合并过了, 因此这一步不会发生冲突.
5. 在开发环境中, 从项目主分支build, pack, 并通过一定的办法发布线上环境.
6. 线上环境元数据从线上分支pull下拉.
7. 启动程序.
8. 同步数据库.
9. 确认发布完成后, 将发布日志发布到内部群, 由项目经理决定发到客户群的最终内容.

方案B

项目启动后, 在适当的时候从产品主干复制一份源码, 并推送到一个新的项目库中.

1. 日常离线修改的元数据和代码, 提交到项目主分支.
2. 日常线上修改的内容, 修改好之后也及时提交到项目主分支.
3. 发布前, 在开发环境中, 从项目主分支build, pack, 并通过一定的办法发布线上环境.
4. 发布前, 在线上pull元数据, 如发生冲突, 在线上环境合并.
5. 合并成功后, 将项目主分支合并回在线分支, 由于上一步中已经合并过了, 因此这一步不会发生冲突.
6. 在项目主分支build, pack, 并通过一定的办法发布线上环境.
7. 线上环境元数据从线上分支pull下拉.
8. 启动程序.
9. 通过设计器同步数据库.
10. 通过设计器执行模块版本升级.
11. 确认发布完成后, 将发布日志发布到内部群, 由项目经理决定发到客户群的最终内容.

编码规范

硬代码编码规范

编码规范是为了:

• 统一编码风格
• 提高产出物性能(包大小, 内存开销, 意外出错等)
• 减少git变更记录中的无效内容.

为此, 我们需要:

• 统一java和typescript的代码编写规范, 并固化到ide项目文件中. (VSCODE: .tslint, idea: setting). 尽量采用IDE现成内置的编码规范, 以降低新环境配置负担.
• 每次提交代码前, 需要格式化代码文件, 并清理无用import. 此项工作最好自动完成;

IDEA操作指南

1. 项目目录点右键, 调出右键菜单, 选择Reformat Code, 如下图:
   
2. 在弹出对话框中勾选Include subdirectories, Optimize imports, Rearange entries, Only VCS changed text, Cleanup code, 然后点Run按钮, 如下图:
   

vscode操作指南

1. 目前的版本的VSCODE已经内置了Typescript扩展, 包括智能提示, 格式化等等, 无需安装其他插件, 只需确保设置正确, 如下图:
   

   
   
   
   
   

2. 代码保存后, 自动格式化+重组织import

数据库

• 所有实体通过设计器维护. 对于设计器无法处理的变更, 允许直接调整数据库, 但调整结果需要符合实体定义;
• 原则上, master中字段和表的增删改都需要同步; 项目中字段和表的增删必须同步, 改不强制要求;
• 原则上, 所有的视图, 函数, 存储过程都需要需通过设计器维护;