mirai/docs/Evolution.md

Mirai - Evolution

Mirai 演进

Mirai 是不断前进的库，目标是提供稳定且高效的 API。
维护者会严谨地推进每一项修改，并提供迁移周期（至少 2 个次版本）。

版本规范

Mirai 的版本号遵循 语义化版本 2.0.0 规范。

在日常开发中, Mirai 会以 -dev-1，-dev-2 等版本后缀发布开发预览版本。这些版本仅用于兼容性测试等目的，无稳定性保证。

在大版本开发过程中，Mirai 会以 -M1, -M2 等版本后缀发布里程碑预览版本。代表一系列功能的完成，但还不稳定。
这些版本里新增的 API 仍可能还会在下一个 Milestone 版本变化，因此请按需使用。

在大版本即将发布前，Mirai 会以 -RC 版本后缀发布最终的预览版本。
RC 表示新版本 API 已经确定，离稳定版发布只差最后的一些内部优化或 bug 修复。

版本选择

稳定性：稳定 (x.y.z) > 发布预览 (-RC) > 里程碑预览 (-M) > 开发 (-dev)。

目的	推荐至少更新到版本
生产环境	x.y.z
希望尽早体验稳定新特性	-RC
无论如何都想体验新特性	-M
为 Mirai 提交 PR	-dev

更新兼容性

对于 x.y.z 版本号:

• 当 z 增加时，只会有 bug 修复，和必要的新函数添加（为了解决某一个问题），不会有破坏性变化。
• 当 y 增加时，可能有新 API 的引入，和旧 API 的弃用。但这些弃用会经过一个弃用周期后才被删除（隐藏）。向下兼容得到保证。
• 当 x 增加时，任何 API 都可能会有变化。无兼容性保证。

弃用周期

一个计划被删除的 API，将会在下一个次版本开始经历弃用周期。

如一个 API 在 1.1.0 起被弃用，它首先会是 WARNING (使用时会得到一个编译警告）弃用级别。
在 1.2.0 上升为 ERROR（使用时会得到一个编译错误）；
在 1.3.0 上升为 HIDDEN（使用者无法看到这些 API)。

HIDDEN 的 API 仍然会保留在代码中并正常编译，以提供二进制兼容性，直到下一个主版本更新。

---

回到 Mirai 文档索引