KossJS 版本管理规范
版本：1.0.0最后修订日期： 2026-04-12
本文档定义了 KossJS 项目的版本号管理规则，旨在确保版本演进清晰、一致，并促进项目与依赖项之间的兼容性理解。本规范基于 语义化版本 2.0.0 制定。
1. 核心术语与要求级别
本文档中，"必须"（MUST）、"不得"（MUST NOT）、"要求"（REQUIRED）、"建议"（RECOMMENDED）、"可以"（MAY）、"可选"（OPTIONAL）等关键词，按 RFC 2119 的表述进行解释。
2. 版本号格式
KossJS 的版本号必须遵循以下格式：
<主版本号>.<次版本号>.<修订号>[-<预发布标识符>.<预发布编号>][+<构建元数据>]各部分说明如下：
| 组成部分 | 名称 | 必需性 | 规则与示例 |
|---|---|---|---|
| <主版本号> | Major | 必需 | 非负整数，不得包含前导零。例如：0，1，42。 |
| <次版本号> | Minor | 必需 | 非负整数，不得包含前导零。例如：0，1，23。 |
| <修订号> | Patch | 必需 | 非负整数，不得包含前导零。例如：0，1，7。 |
| -<预发布标识符>.<预发布编号> | Pre-release | 可选 | 标识符为小写字母字符串，编号为正整数，且不得包含前导零。例如：-dev.1，-rc.3。 |
| +<构建元数据> | Build metadata | 可选 | 由字母、数字、连字符组成的字符串。例如：+20250226，+nightly.2025.03。 |
有效的版本号示例：
- 1.2.3
- 2.0.0-dev.1
- 0.1.0-beta.2+20250226
3. 核心版本（X.Y.Z）的递增规则
版本号的核心部分（<主版本号>.<次版本号>.<修订号>）必须始终根据以下规则递增。
- 主版本号（X）：当进行了不兼容的 API 或核心功能变更时递增。
- 次版本号（Y）：当以向后兼容的方式添加新功能时递增。
- 修订号（Z）：当进行了向后兼容的问题修复时递增。
4. 预发布版本阶段
在进入正式版之前，或为正式版发布候选时，必须使用预发布后缀来标识其成熟度。KossJS 定义以下预发布阶段：
| 阶段 | 标识符 | 版本号示例 | 说明 |
|---|---|---|---|
| 开发版 | dev | 0.1.0-dev.1 | 活跃开发中的内部快照，功能不完整或不稳定，仅供核心开发者使用。 |
| 内部测试版 | internal | 0.1.0-internal.1 | 完成部分功能，交付给内部测试团队验证，可能存在较多缺陷。 |
| Alpha 测试版 | alpha | 0.1.0-alpha.1 | 核心功能基本完成，面向有限的外部测试者收集早期反馈，预期存在较多问题。 |
| Beta 测试版 | beta | 0.1.0-beta.1 | 功能已完整，主要缺陷已修复，面向更广泛的用户进行公开测试。 |
| 候选发布版 | rc | 0.1.0-rc.1 | 接近正式版本，若无重大问题，将直接作为正式版发布。 |
预发布规则：
- 预发布标识符必须为小写字母。
- 预发布编号必须为从 1 开始递增的正整数。
- 当版本从一个阶段演进到下一个阶段时，编号必须重置为 1。
5. 版本优先级
版本优先级必须严格按语义化版本规则确定：
- 版本号按顺序比较：主版本号、次版本号、修订号。数值越大，版本越新。
- 正式版本（无预发布后缀）的优先级总是高于任何预发布版本。例如：1.0.0 > 1.0.0-rc.1。
- 对于有相同核心版本号的预发布版本，其优先级由标识符决定。标识符按字典序比较：dev < internal < alpha < beta < rc。
6. 规范的修订
本规范自身将使用语义化版本进行管理。对规范的任何修订（包括规则的澄清或变更），都必须更新此文档的版本号，并记录于下：
| 版本 | 日期 | 修订说明 | 作者 |
|---|---|---|---|
| 0.1.0-dev.2 | 2026/04/12 | 初始版本，基于 SemVer 2.0.0 建立 | XstarRelight |
7. 版本历史
| 版本 | 日期 | 主要变更 |
|---|---|---|
| 0.1.0-dev.1 | 2026/04 | 初始版本：Boa 引擎嵌入、C ABI、模块加载、事件循环 |
| 0.1.0-dev.2 | 2026/04 | Python 接口封装、Fetch API、模块解析器 |
| 0.1.0-dev.3 | 2026/04 | Worker 线程池、跨平台 CI |
| 0.1.0-dev.4 | 2026/04 | Node.js 兼容层（internalBinding、process、模块系统）、标准库扩展 |
| 0.1.0-dev.5 | 2026/06 | stdlib 扩展（URLSearchParams、assert、os、path、timers）、Worker 安全加固（CWE-94、CWE-400）、Python 接口整合、跨平台修复（Android TLS） |
| 0.1.0-dev.6 | 2026/06 | Senri FFI 子系统、N-API 兼容层、Buffer 全局对象、process.dlopen、事件循环扩展、GPL 许可证输出 |
| 0.1.0-dev.7 | 2026/06 | 28 位细粒度能力位系统、沙箱安全三层机制（能力位 + 审核掩码 + 审核回调）、审核调试模式、FFI 沙箱测试、跨平台编译修复（iOS/Android/鸿蒙/Linux aarch64）、内存管理修复 |
| 0.1.0-dev.8 | 2026/06 | stable 模式（FFI/Worker 隔离）、koss_is_stable()、TypeScript 接口封装、Python 接口新增 get_capabilities()/is_stable、worker_threads 模块拦截、C ABI stable 感知错误消息、Node.js 内置库简化重构（移除官方源码依赖，zlib 压缩支持，TCP Socket 持久化） |
| 0.1.0-dev.9 | 2026/06 | Node.js 内置库实现简化（移除 Node.js 官方源码依赖）、zlib 压缩支持（flate2 crate）、TCP Socket 持久化、7 个新测试文件、代码量减少约 10 万行 |