关于Jigsaw的版本策略

关于Jigsaw的版本

版本发布时间

每月月中和月末固定各发布一个版本

版本号的规则和约定

Jigsaw采用通用的三段式版本规则，例如一个版本号为 v1.3.9，这里用点分的三段，有不同的含义，从左到右：

• 第一位数字1的含义是主版本号，一般来说，只在有里程碑意义的变更出现时，才会更新这第一位数字；
• 第二位数字3的含义是大版本号，一般来说，Jigsaw只在需要合入破坏性变更时，才会更新这第二位数字；
• 第三位数字9的含义是小版本号，我们承诺，这位数字的递增意味着所有对外公开的API都是向下兼容的；

有时候，还会有一个额外的字段表示版本的状态，常见的状态有如下这些：

• beta 含义是：当前版本处于beta状态，例如v1.3.9-beta1，按照通用的版本规则，处于beta状态的版本的API仍然有较大的可能性发生破坏性修改，应该慎重选择这类版本；
• rc 含义是：当前版本处于预发布状态，例如v1.3.9-rc1，按照通用的版本规则，处于rc状态的的版本的API基本上已经稳定且承诺保持向下兼容，rc阶段的各个版本均只做bugfix修改，不合入新功能；

rc是 release candidate 单词的缩写

哪些是“对外公开的API”？

笼统但是简单的说：凡是可以在Jigsaw官网文档里可以查阅到的api，都是“对外公开的API”，除此以外的所有API，均属于非公开的API，需要特别注意的是，非公开的API的兼容性我们是不承诺的，这一点是为了减轻Jigsaw演进的兼容性负担而定的，请理解。

典型的非公开的API包含但不限于：

• 所有以下划线开头的方法或者变量；
• 组件的html模板的dom结构；
• 组件的html模板里的样式class名；
• 所有被标记为@internal的方法、变量、函数；

NPM的版本升级规则简述

细心的小伙伴可能已经发现了，package.json文件里的版本号前，总是一个符号，常见的符号有 ^ 和 ~，还有的没有这个个符号，那么这几个符号都有啥含义呢？

• ^ 表示自动升级版本到第二段的最新版本，例如你当前正在使用的版本是v1.1.9，并且Jigsaw发布了一个版本号为v1.2.0-beta1的版本，则执行npm install时，npm将会把jigsaw的版本升级到v1.2.0-beta1。在生产环境下，应该谨慎使用这个符号！
• ~ 表示自动升级版本到第三段的最新版本，在前面例子中，npm在此时是不会升级jigsaw版本到v1.2.0-beta1的，但是如果jigsaw发布了v1.1.12，则npm会自动将jigsaw的版本升级到v1.1.12。强烈推荐在生产环境下使用这个符号！
• 无符号，表示冻结当前jigsaw版本，此时，无论jigsaw发布那样的版本，npm都不会升级jigsaw的版本。在生产环境中，也可以考虑使用这个规则，以获得编译环境的尽可能稳定，但是一旦需要使用更新版本的jigsaw版本，则需要编辑package.json文件来手工升级jigsaw版本，稍微麻烦一些。

不仅仅要关注Jigsaw的版本号前的这个符号，其他使用依赖包的版本号前的符号，都需要关注。

如何升级Jigsaw版本

• 最简单的，你只要执行npm install就行了；
• 也可以执行 npm install @rdkmaster/[email protected] 来强制安装某个版本的Jigsaw，但这个方式仅限于开发环境，不建议在编译/CI环境下这么做；

多版本演进策略

正如前面说过的，我们承诺：小版本的演进，我们会严格保持所有公开API的向下兼容（非公开API不一定保持向下兼容）。

基于这个承诺，同时为了让Jigsaw的用户能够更快的使用到Jigsaw的新特性（包含新组件、新功能），但凡一个新特性的合入不会引入破坏性修改，我们就会尽量在小版本上继续演进。但是一旦某个特性不得不引入破坏性修改，为了继续秉持我们的承诺，Jigsaw将不得不通过升级大版本的方式来落实这些破坏性修改。

此时，Jigsaw将会同时发行多个大版本，例如，我们近期一直在计划发布下一个大版本v1.2。当v1.2发布之后，现行的v1.1.x版本将会和v1.2.x同时并行演进，但是我们会有侧重：对于v1.1，我们只修复故障，这意味着如果没有特别的需要，新特性我们将不再合入v1.1，而只合入v1.2。

我们承诺的另一个事情是：但凡版本较低的大版本（例如v1.1）只要有外场在使用，我们就会一直在这个分支上修复故障。可能的话，还请尽快升级到更新的大版本，好减轻我们的维护负担。

相关链接

如何部署一个Jigsaw应用，请看这里