Litefs 版本演进路线（0.10.0 → 1.0.0）

定位：生产就绪 —— API 稳定承诺 + 质量硬指标达标基线版本：v0.9.0（cb2988f）编制日期：2026-10-21 对标对象：Starlette（近 8 年唯一真正走完 0.x → 1.0 的同代 ASGI 框架）核心原则：硬性标准未全部达成，不升 v1.0

一、路线调整说明（决策变更记录）

1.1 变更内容

项	原方案（2026-10-21 初版）	现方案（本版）
交付形态	v1.0.0 一次性执行 P0–P3 全部内容	拆分为 6 个 0.x.x 版本，逐版交付可发布成果
破坏性变更	集中在 v1.0.0 一次性执行（B1–B8）	分散到各 0.x 版本，利用 SemVer 0.x 允许破坏的特性
v1.0.0 性质	「大量变更的交付版本」	「稳定性声明版本」 —— 几乎零代码变更，只做 API 冻结宣告 + 政策定稿 + 标签
晋级条件	一次性满足 15 条 DoD	每一版 0.x 都是可发布版本；15 条 DoD 全部达成才允许打 v1.0.0 标签
发布粒度	1 次大版本	7 次发布（0.10.0 – 0.15.0 + 1.0.0），每次均含 CHANGELOG 与 Release Notes

变更理由：行业数据显示 0.x → 1.0 的中位耗时是 3–8 年（Starlette 7.8 年，Flask 约 8 年，FastAPI 8 年仍未达成 1.0）。把 3–8 年的工程量压进单次发布，风险不可控且无法持续验证。分版本路线让每一批改动都被真实用户验证过 —— 1.0 应该是「验证完毕的既有事实」，而不是「一次性押注的未来承诺」。

1.2 SemVer 0.x 下的破坏性变更处理

SemVer 规范中 0.y.z 阶段「任何变更都可能发生」，因此：

0.x 阶段：0.MINOR 位递增即视为破坏性版本（Django 1.0 前、Flask 1.0 前均遵循此惯例）。跨 0.MINOR 边界的破坏性变更无需弃用期，但必须在 CHANGELOG 单列 Changed / Removed 专章。
1.0 之后：破坏性变更只走 major，且弃用项须在移除前保留至少 2 个 feature release（对标 Django）。
0.x 阶段的过渡期保护：对用户可见的公共 API（litefs.__all__ 中的 stable 分级符号），即使在 0.x 阶段也须至少保留 1 个 minor 版本的 DeprecationWarning 过渡；纯内部重构（_ 前缀符号）不受此约束。

1.3 与既有决策的关系

决策「范围定位 = 聚焦稳定性硬指标」保持不变。
决策「Python 基线 = 3.10–3.14」保持不变，落地于 v0.14.0。
决策「ASGI 深度 = 渐进增强」保持不变，落地于 v0.13.0。
原决策「破坏性变更 = 1.0.0 一次性执行」被本方案覆盖，改为分散执行。

二、为什么是现在，以及对标谁

2.1 行业 1.0 的现实参照

框架	当前稳定版	是否到 1.0	1.0 首发	0.x → 1.0 耗时	Python 要求
Starlette	1.9.0	✅	2026-03-22	约 7.8 年	>=3.11
FastAPI	0.156.6	❌ 至今 0.x	—	8 年未达成	>=3.10
Django	6.1.2	✅	2008-09-04	约 2.7 年	>=3.12
Flask	3.1.3	✅	2018-04-26	约 8 年	>=3.9
Tornado	6.5.10	✅	2010-07-23	约 2 个月	>=3.9
Sanic	25.12.1	❌ 跳过 1.x	—	—	>=3.10
Litestar	2.25.0	❌ 跳过 1.x	—	—	>=3.8
aiohttp	3.14.5	❌ 仍 3.x	—	—	>=3.10
Quart	0.23.1	❌ 仍 0.x	—	—	>=3.13

结论：0.x → 1.0 的中位耗时是 3–8 年。 FastAPI 用了 8 年仍未发布 1.0，是最值得警惕的样本 —— 它的问题不是功能不足，而是始终没有对 API 稳定性做出可依赖的承诺。

因此 Litefs 的 1.0 不以功能数量取胜，而以「承诺的可信度」取胜：对标 Starlette 1.0 的做法，而不是对标 FastAPI 的功能面。

2.2 业界公认的「可以叫 1.0」判据（按重要性排序）

#	判据	行业实践	Litefs 现状	交付版本
1	成文的 API 稳定性承诺 + 严格 SemVer	Django《API stability》指南、Starlette 1.0 博客「We'll follow SemVer strictly」	❌ 无	v0.10.0
2	长弃用期，破坏性变更只走 major	Django：弃用后至少保留 2 个 feature release	❌ 无弃用机制	v0.10.0
3	覆盖率成为硬门禁	FastAPI / Starlette 公开声明 100% 覆盖率，pytest 开 `filterwarnings=error`	⚠️ 72.2%，无 `fail_under`	v0.12.0
4	完整类型注解 + `py.typed` + `mypy --strict`	Starlette / FastAPI 均 `strict = true`；Django 是唯一无 `py.typed` 的一线框架	❌ 无 `py.typed`，53 模块豁免	v0.11.0
5	明确的 Python 版本淘汰节奏	Starlette 1.8 抬到 3.11、Sanic 25.12 弃 3.9、Quart 0.23 抬到 3.13	⚠️ 3.8–3.12，3.8 已 EOL	v0.14.0
6	安全响应闭环（GHSA / CVE / 分支回补）	Django 明确「security trumps the compatibility guarantee」	⚠️ 有依赖审计，无响应流程	v0.15.0
7	版本化文档 + 迁移指南 + 废弃时间表	Django 有专门的 Deprecation Timeline 页	❌ 无	v0.10.0 / v0.15.0
8	生态可互操作（ASGI 中间件规范、插件注册）	Starlette `BaseHTTPMiddleware` 互操作	❌ 无 lifespan、无 entry_points	v0.13.0

2.3 Litefs 硬性标准总表（15 条 DoD）

全部满足方可发布 v1.0.0。每条标注交付版本。

#	硬性标准	判定方式	交付版本
H1	《API 稳定性与 SemVer 政策》已发布并经评审	文档存在 + 评审记录	v0.10.0
H2	196 个公共符号完成 `stable` / `experimental` 分级	清单文件 + 逐项 `__all__` 核对	v0.10.0
H3	全部源文件 ≤600 行	脚本校验纳入 CI	v0.10.0
H4	`py.typed` 随 wheel 正确分发	解包 wheel 验证	v0.11.0
H5	`mypy --strict src/` 零错误、零豁免	CI lint 门禁 `allow_failure: false`	v0.11.0
H6	弃用机制与废弃时间表就位	`DeprecationWarning` 工具 + 时间表文档	v0.10.0
H7	整体覆盖率 ≥85%	`coverage report --fail-under=85`	v0.12.0
H8	核心模块覆盖率 ≥80%	`handlers/socket.py` / `server/greenlet.py` / `app/server_mixin.py` ≥80%，`websocket/` ≥75%	v0.12.0
H9	`filterwarnings = error` 生效	pytest 配置核对	v0.12.0
H10	`TestClient` 与 `tests/conftest.py` 就位	单元测试 + 文档示例	v0.12.0
H11	ASGI lifespan 可被 uvicorn / hypercorn 托管	集成测试用例	v0.13.0
H12	ASGI 中间件签名兼容 + `entry_points` 插件可被发现	集成测试 + 示例	v0.13.0
H13	GitHub PR 级 CI 全部通过 + Python 3.10–3.14 矩阵全绿	PR 状态检查 + CI 矩阵	v0.14.0
H14	`SECURITY.md` + SBOM + 签名就绪 + 版本化文档站	发布产物核验	v0.15.0
H15	迁移指南 + 变更日志齐备，无未登记的破坏性变更	文档评审 + 破坏性变更清单逐条核对	v0.15.0 / v1.0.0

三、0.x.x 版本路线总览

3.1 版本序列

v0.9.0  ── 2026-10-21 ── 技术债务清理 & 架构统一（已发布）
   │
v0.10.0  契约与结构重构   API 政策 + 符号分级 + 弃用机制 + 拆分 5 个大文件
   │
v0.11.0  类型系统与打包契约 py.typed 落盘 + mypy --strict 零豁免
   │
v0.12.0  测试基础设施与质量基线 conftest + TestClient + 覆盖率 ≥85% + warnings 严格化
   │
v0.13.0  ASGI 协议与插件生态  lifespan + streaming + 中间件兼容 + entry_points
   │
v0.14.0  工程化与 Python 基线收敛 PR CI 门禁 + 删 setup.py + 依赖 optional 化 + 3.10–3.14
   │
v0.15.0  发布基础设施与安全闭环 SECURITY.md + SBOM/签名 + 版本化文档站 + 迁移指南
   │
v1.0.0   稳定性声明发布   API 冻结宣告 + 政策定稿 + 标签（几乎零代码变更）
   │
v1.0.x   仅安全与严重缺陷修复（1.0 稳定分支）
   │
v1.1.x   OpenTelemetry 可选中间件
   │
v1.2.x   HTTP/2 支持
   │
v2.0.x   ASGI 原生重写 / HTTP/3 / 边缘轻量构建

3.2 判据 × 版本覆盖矩阵

版本	主题	绑定判据	可发布的独立价值	工作量
v0.10.0	契约与结构重构	① ② ⑦	用户可依赖「哪些 API 会变、什么会被弃用」，代码结构达标	≈7d
v0.11.0	类型系统与打包契约	④	首次提供完整类型支持，IDE 补全与静态检查全量可用	≈6d
v0.12.0	测试基础设施与质量基线	③	质量可度量、可门禁，回归风险显著下降	≈12d
v0.13.0	ASGI 协议与插件生态	⑧	可被 uvicorn/hypercorn 直接托管，插件生态开放	≈10.5d
v0.14.0	工程化与 Python 基线收敛	⑤	安装更轻，Python 淘汰节奏明确	≈8d
v0.15.0	发布基础设施与安全闭环	⑥ ⑦	供应链可信，安全响应有流程	≈7d
v1.0.0	稳定性声明发布	全部 8 条	兑现可依赖的长期承诺	≈4d
			合计	≈54.5d

每一版都是完整可发布版本：CHANGELOG 更新、Release Notes、全量回归通过、性能基线不回退、GitHub Release 打标。不存在「半成品中间态发布」。

四、各版本详细规划

4.1 v0.10.0 —— 契约与结构重构

行业第一判据。先立承诺，再动结构。

#	任务	产出	验收标准	工作量
0.10-1	编写《Litefs API 稳定性与 SemVer 政策》	`docs/source/api-stability.md`	明确：稳定 API 定义、弃用流程、破坏性变更仅走 major、弃用后至少保留 2 个 minor（对标 Django）	1d
0.10-2	公共 API 分级与冻结	`litefs/_stable.py` 清单 + 各子包 `__all__` 标注	196 个符号逐个判定 `stable` / `experimental` / `private`；`private` 加 `_` 前缀或移出 `__all__`	2d
0.10-3	弃用机制与时间表	`DeprecationWarning` 工具 + `docs/source/deprecation-timeline.md`	弃用项带「计划移除版本」；迁移指南模板就位	1d
0.10-4	拆分 5 个超 600 行文件	见 §六表	全部 ≤600 行；公开 API 零变更；全量回归通过	3d

本版允许的破坏性变更：B4（内部符号加 _ 前缀）、B5（ValidationError 导入路径收敛）、B6（core.py 拆分后私有方法迁移）。

支撑项（已完成，不占用版本额度）：

支撑项	内容	验收标准
JSON 序列化换用 orjson	新增 `litefs/_json.py` 抽象层，框架内 24 处 `import json` 全部替换	源码无 `import json` 残留；`dumps_ascii` 保证 Memcache 值契约不变；全量回归通过
公共 API 分级注册表	新增 `litefs/_stable.py`，符号按 `stable` / `provisional` / `internal` 三级登记	契约测试强制每个模块必须被分类

出口门禁：

[x] H1、H2、H3、H6 达成
[x] 全部源文件 ≤600 行
[x] 全量 pytest 通过，无行为回归
[x] CHANGELOG 含 Changed / Removed 专章

v0.10.0 交付备注：分级实际落地为 stable / provisional / internal 三级，登记 70 个 stable 模块 410 符号 + 32 个 provisional 模块 138 符号（合计 548），较原计划的 196 符号覆盖更完整；弃用机制与契约测试（tests/unit/test_api_contract.py）提前至本版完成。5 个超限文件全部拆分至 ≤600 行，公开 API 零变更。

4.2 v0.11.0 —— 类型系统与打包契约

#	任务	产出	验收标准	工作量
0.11-1	`py.typed` 落盘	`src/litefs/py.typed` + 打包配置	wheel 内实际包含 `py.typed`（`twine check` + 解包验证）	0.5d
0.11-2	`mypy --strict` 全量收敛	53 个豁免清零	`mypy --strict src/` 零错误；CI 门禁切换为 strict	5d
0.11-3	公共 API 标注补齐	稳定符号补全类型注解与 docstring	196 个 stable 符号 100% 有类型注解与文档	0.5d

出口门禁：

[ ] H4、H5 达成
[ ] mypy --strict src/ 零错误、零豁免（CI allow_failure: false）
[ ] wheel 解包确认含 py.typed
[ ] 运行时行为零变化（回归全绿）

4.3 v0.12.0 —— 测试基础设施与质量基线

本版是 1.0 最大的实质风险所在：框架最核心的自研服务器代码覆盖率最低。

#	任务	产出	验收标准	工作量
0.12-1	核心服务器覆盖率补齐	新增测试模块	`handlers/socket.py` ≥80%、`server/greenlet.py` ≥80%、`app/server_mixin.py` ≥80%、`websocket/` ≥75%	6d
0.12-2	`tests/conftest.py` + 共享 fixtures	测试基础设施	`app` / `client` / `tmp_config` / `mock_redis` / `mock_memcache` 等 fixtures；测试重复代码下降	1d
0.12-3	`TestClient` 实现	`litefs/testclient.py`	httpx 驱动，支持 WSGI + ASGI 两种 app，Cookie 持久化、状态码断言	2d
0.12-4	覆盖率补齐（非核心模块）	新增/扩充测试	整体 ≥85%；`app/` `cache/` `session/` `routing/` `middleware/` `auth/` 均 ≥80%	5d
0.12-5	pytest 严格化	`pyproject.toml`	启用 `filterwarnings = error`；`--strict-markers --strict-config` 保持；`coverage fail_under = 85`	1d

本版允许的破坏性变更：B8（pytest filterwarnings=error，仅影响项目自身测试）。

出口门禁：

[ ] H7、H8、H9、H10 达成
[ ] coverage report --fail-under=85 通过
[ ] pytest 在 filterwarnings = error 下全绿
[ ] 性能回归门禁 RPS ≥ v0.9.0 基线

4.4 v0.13.0 —— ASGI 协议与插件生态

#	任务	产出	验收标准	工作量
0.13-1	ASGI lifespan 协议	`handlers/asgi.py` 支持 `scope['type'] == 'lifespan'`	uvicorn / hypercorn 直接托管 Litefs ASGI app 正常启停；`startup` / `shutdown` 钩子可注册	2d
0.13-2	原生 ASGI streaming 响应	响应对象直通 `send()`	不再经过 WSGI environ 转换；SSE / 流式大文件不缓冲	3d
0.13-3	ASGI 中间件签名兼容	`litefs/middleware/asgi.py`	Starlette 风格 `async def mw(request, call_next)` 中间件可直接挂载	2d
0.13-4	`entry_points` 插件发现	`plugins/loader.py` 双通道	支持 `[project.entry-points."litefs.plugins"]`；保留现有目录扫描	1.5d
0.13-5	集成测试与示例	测试 + `examples/`	uvicorn/hypercorn 托管用例；entry_points 示例；streaming 示例	2d

出口门禁：

[ ] H11、H12 达成
[ ] uvicorn / hypercorn 托管 Litefs ASGI app 启停正常
[ ] Starlette 风格中间件可直接挂载并通过用例
[ ] entry_points 插件可被发现（集成测试通过）

4.5 v0.14.0 —— 工程化与 Python 基线收敛

#	任务	产出	验收标准	工作量
0.14-1	GitHub PR 级 CI 门禁	`.github/workflows/ci.yml`	PR 触发 lint（flake8+ruff+mypy strict）+ test（3.10–3.14 矩阵）+ coverage 门禁；`allow_failure: false`	2d
0.14-2	删除 `setup.py`	单一 `pyproject.toml`	全部元数据迁入 PEP 621；`pip install .` 与 `python -m build` 均通过	1d
0.14-3	核心依赖 optional 化	`pyproject.toml` extras 重整	`SQLAlchemy` / `watchdog` / `greenlet` 移出必装；`cache/cache.py` 与 `database/core.py` 的模块级 import 改为懒加载	2d
0.14-4	extras 矩阵重整	`litefs[standard\|full\|db\|server\|mail\|i18n\|monitoring\|dev\|docs]`	每个 extra 有明确用途与文档说明；`litefs[full]` 可复现全部功能	1d
0.14-5	Python 基线收敛 3.10–3.14	`requires-python` + classifiers + CI 矩阵	弃 3.8/3.9；新增 3.13/3.14；`black` target-version 同步	1d
0.14-6	可选依赖缺失时的友好提示	启动期检查	缺失可选依赖时给出明确的中文错误提示与安装命令（不做静默降级）	1d

本版允许的破坏性变更：B1（核心依赖 optional 化）、B2（删除 setup.py）、B3（Python 基线 3.10+）。

出口门禁：

[ ] H13 达成
[ ] PR 级 CI 三级门禁上线，Python 3.10–3.14 矩阵全绿
[ ] pip install litefs 不再拉入 SQLAlchemy / watchdog / greenlet
[ ] 迁移说明已在 CHANGELOG 给出（pip install litefs[full] 一键方案）

4.6 v0.15.0 —— 发布基础设施与安全闭环

#	任务	产出	验收标准	工作量
0.15-1	`SECURITY.md` 与 CVE 响应流程	安全策略文档 + 私有报告通道	明确漏洞报告方式、响应时限、分支回补规则（对标 Django「安全优先于兼容承诺」）	0.5d
0.15-2	SBOM 与签名发布	`cyclonedx-py` 产物 + Sigstore 签名	每版发布附带 SBOM；wheel/sdist 签名并在 PyPI 展示	1.5d
0.15-3	版本化文档站	ReadTheDocs 配置	按版本发布；每版含迁移指南与废弃时间表	1.5d
0.15-4	LTS 政策	政策文档	对标 Django：每 2 年一个 LTS、支持期 3 年、LTS 命名为 `X.0`	0.5d
0.15-5	迁移指南 `migration-v1.md`	文档	从 v0.9.0 逐版升级到 v0.15.0 的操作说明 + 0.15.0 → 1.0.0 预告	1.5d
0.15-6	全量回归 + 性能基线复核	回归报告	覆盖率 ≥85%、mypy strict 零错误、pytest 全绿、RPS ≥ v0.9.0 基线 100%	1.5d

出口门禁：

[ ] H14、H15 达成
[ ] SBOM 与签名产物随发布产出
[ ] 文档站可按版本访问
[ ] 迁移指南覆盖 0.9.0 → 0.10.0 → … → 0.15.0 的全部破坏性变更

4.7 v1.0.0 —— 稳定性声明发布

本版几乎不做代码变更。 当 0.10.0 – 0.15.0 逐版交付完毕、15 条硬性标准全部达成后，1.0.0 只是把「事实上已经稳定」的状态正式宣告出来。

#	任务	验收标准	工作量
1.0-1	API 冻结确认	196 个符号分级清单签字冻结，stable 集合不再变更	0.5d
1.0-2	《API 稳定性与 SemVer 政策》正式版定稿	文档从「草案」转「生效」，明确 1.0 后的兼容承诺	0.5d
1.0-3	`CHANGELOG.md` 破坏性变更汇总专章	汇总 0.9.0 → 1.0.0 全部 `Changed` / `Removed` 条目	0.5d
1.0-4	全量回归 + 性能基线复核	覆盖率 ≥85%、mypy strict 零错误、pytest 全绿、RPS ≥ v0.9.0 基线 100%	1d
1.0-5	`Development Status` 分类升级	`4 - Beta` → `5 - Production/Stable`（B7）	0.5d
1.0-6	打标签 + 发布 + GitHub Release	`v1.0.0` 标签、PyPI 正式发布、Release Notes	0.5d
1.0-7	`1.0` 稳定分支	建立 `1.0` 分支，仅接受安全与严重缺陷修复	0.5d

出口门禁（硬性）：

[ ] H1 – H15 全部达成，无一例外
[ ] 0.10.0 – 0.15.0 全部已发布并可被用户安装
[ ] Development Status 为 5 - Production/Stable
[ ] v1.0.0 相对 v0.15.0 的代码变更量 ≤ 政策性改动（无功能性变更）

五、破坏性变更清单与分配

每项均须在 docs/source/migration-v1.md 中给出前后对照。

#	变更	影响	兼容处理	分配版本
B1	核心依赖 optional 化	`pip install litefs` 不再装 SQLAlchemy / watchdog / greenlet	需功能者改用 `litefs[db]` / `litefs[standard]`；提供一键迁移提示	v0.14.0
B2	删除 `setup.py`	仅影响源码安装者	`pip install -e .` 行为不变	v0.14.0
B3	Python 基线 3.10+	弃 3.8 / 3.9	`Requires-Python` 声明；文档给出升级指引	v0.14.0
B4	内部符号加 `_` 前缀	少数用户可能引用了内部符号	保留旧名别名 + `DeprecationWarning` 一个 minor 周期	v0.10.0
B5	`ValidationError` 导入路径收敛	`forms.py` / `validators.py` / `exceptions.py` 三处	统一到 `litefs.exceptions`；旧路径保留别名 + 警告	v0.10.0
B6	`core.py` 拆分后的私有方法迁移	极少数用户直接调 `core.py` 私有方法	`_` 前缀标记为私有，文档明示不承诺兼容	v0.10.0
B7	`Development Status` 分类升级	无运行时影响	`4 - Beta` → `5 - Production/Stable`	v1.0.0
B8	pytest `filterwarnings=error`	仅影响项目自身测试	用户测试不受影响	v0.12.0

范围约束：以上 8 项之外，各 0.x 版本不引入新的破坏性变更。已弃用但未列入的项，一律推迟到 2.0。

六、超 600 行文件拆分方案（v0.10.0 交付）

文件	当前行数	拆分方案	目标
`handlers/socket.py`	828	抽出 `socket_request.py`（请求解析）/ `socket_response.py`（响应序列化）/ `socket_multipart.py`（multipart 解析）	3 个 ≤350 行
`server/greenlet.py`	780	抽出 `greenlet_request.py`（请求处理）/ `greenlet_worker.py`（多进程 worker 与信号）	2 个 ≤450 行
`error_pages.py`	775	模板外置为 `templates/error/*.html`，类内仅保留渲染逻辑	≤200 行
`handlers/base.py`	639	抽出 `handlers/properties.py`（请求属性访问器）	2 个 ≤400 行
`config.py`	628	抽出 `config/env.py`（环境变量解析）	2 个 ≤400 行

约束：拆分过程中公开 API 与运行时行为零变化；每个文件拆分后立即跑全量回归；优先使用延迟导入规避循环依赖（core.py 拆分已验证该路径可行）。

七、风险与对策

风险	等级	对策
核心服务器覆盖率补齐耗时超预期	高	优先用「协议级」测试（构造真实 socket 报文驱动 `SocketRequestHandler`）而非逐方法 mock，可显著压缩用例数；必要时将 v0.12.0 拆为 v0.12.0 / v0.12.1 两版
`mypy --strict` 收敛后暴露大量 `Any` 泄漏	高	0.11-2 与 0.12-1 并行；先收敛 `app/`（已有基础），再向外扩散；必要时以 `TypeAlias` 收窄边界类型
optional 化后用户环境碎片化	中	提供 `litefs[full]` 一键全装；启动时对缺失可选依赖给出明确的中文错误提示与安装命令（不做静默降级）
0.x 版本序列拉得过长，用户产生疲劳	中	每版周期控制在 1–2 个迭代；每版必须有可感知的独立价值（类型支持 / 质量门禁 / ASGI 兼容 / 轻安装 / 安全闭环）
1.0 承诺后被紧急修复破坏	中	建立 `1.0` 稳定分支；约定紧急修复需走补丁号且必须补回归用例
性能回退	中	每版复用 `tests/performance/thresholds.json` 门禁，RPS 不得低于 v0.9.0 基线
文档版本化与代码脱节	低	CI 中加「文档代码块可执行性」抽样检查

八、版本策略、LTS 与弃用政策

8.1 里程碑与版本策略

0.x 阶段（v0.10.0 – v0.15.0）：minor 递增即可能含破坏性变更
   每一版独立可发布、独立验证、独立维护

1.0 之后：严格 SemVer
   破坏性变更只走 major；弃用项移除前至少保留 2 个 feature release

8.2 LTS 政策（对标 Django）

规则	内容
命名	`X.0` 为 LTS 版本（如 `1.0`）
频率	每 2 年一个 LTS
支持期	3 年（mainstream 约 8 个月 + extended 约 2 年）
微版本	不限（如 Django 4.2 出了 30 个微版本）
回补	同一 LTS 分支内的安全修复同时回补到上一个 LTS
优先级	安全问题优先于向后兼容承诺

8.3 弃用策略

弃用项必须同时标注「替代方案」与「计划移除版本」
0.x 阶段：纯内部重构可直接 break（SemVer 允许）；用户可见的 stable 公共 API 须至少保留 1 个 minor 的 DeprecationWarning 过渡
1.0 之后：弃用后至少保留 2 个 feature release 才可移除，且移除只发生在 major 版本
每次移除在 CHANGELOG.md 单列 Removed 专章

九、v1.x 长期技术方向

方向	说明	目标版本
协议层抽象	HTTP / WSGI / ASGI / WebSocket 统一为 Protocol 抽象层，新协议只需实现接口	v2.x
ASGI 原生化	scope / receive / send 直通，WebSocket 纳入 ASGI scope，可与 Starlette 中间件完全互操作	v2.x
HTTP/2 / HTTP/3	`h2` 帧层 / aioquic QUIC 栈	v1.2 / v2.x
OpenTelemetry	原生 `OpenTelemetryMiddleware`，与现有 Prometheus 并存	v1.1
边缘轻量构建	去除 SQLAlchemy / greenlet 重依赖，产出 `litefs-lite` 变体，支持 Serverless	v2.x
热点路径加速	路由匹配与序列化路径的 Rust / C 扩展，uvloop 集成	v2.x
插件市场	基于 `entry_points` 的官方插件目录与兼容性矩阵	v1.3

十、文档产出物

文档	路径	交付版本
API 稳定性政策	`docs/source/api-stability.md`	v0.10.0
公共 API 分级清单	`docs/source/api-stability.md`（附录，196 个符号逐项判定）	v0.10.0
弃用时间表	`docs/source/deprecation-timeline.md`	v0.10.0
迁移指南	`docs/source/migration-v1.md`	v0.15.0
安全策略	`SECURITY.md`（仓库根目录）	v0.15.0
本文	`docs/source/release-roadmap.md`	本方案

文档维护: 开发团队 评审状态: 待评审 上次更新: 2026-10-21