Deprecation policy（弃用政策）

UnifiedQuantum 使用 SemVer 2.0.0 进行版本管理。本页说明项目在 0.0.x → 0.1.0 升级窗口内的兼容性承诺 与弃用流程。所有维护者、贡献者、下游用户都应以此为准。

TL;DR：任何在 0.0.x 中触发 DeprecationWarning 的公共 API，在 0.1.0 中会被移除或不再保证兼容性。 想要安全跨过 0.1.0 边界，请在 0.0.x 期间清理所有 DeprecationWarning。

0.1.0 兼容性悬崖

所有当前在 0.0.x 中被标记为 DeprecationWarning 的公共 API （包括类、函数、关键字参数、CLI 选项、配置键、URL 路由）在 0.1.0 中会被彻底移除，或者不再保证与 0.0.x 的行为兼容。

具体含义：

  • 0.0.x → 0.0.y：强兼容承诺。任何被 DeprecationWarning 标记的旧 API 在所有 0.0.x 子版本内都会 保留原行为，方便用户迁移。

  • 0.0.x → 0.1.0：断点升级。旧 API 可能直接 从代码库中删除，或者改为只保留同名占位实现而抛 NotImplementedError。 调用旧形式的代码可能会以编译错误、运行时报错或语义改变的方式失败。

  • 0.1.0 之后：除非另有声明，0.1.0 才是 正式 “new API only” 的起点，后续版本将按 SemVer 正常承诺。

未来若在 0.0.x 末期再引入新的 DeprecationWarning，这些新增弃用项 同样适用 0.1.0 悬崖，除非随附条目明确给出更晚的删除版本。

公共 API 的定义

下述范围视为 公共 API，受兼容性政策约束：

  • 直接通过 from uniqc import X 暴露的符号 （见 uniqc/__init__.py）。

  • 任何在 API 参考 中已有文档的子模块、类、 函数、属性。

  • uniqc CLI 已经在 --help 中列出的子命令、选项、参数。

  • 网关 HTTP API 中以 /api/... 暴露的稳定路由。

  • ~/.uniqc/config.yaml 配置文件中的稳定配置键。

下述范围 不是公共 API，没有兼容性承诺，随时可以变化：

  • 以单下划线开头的对象（如 uniqc._deprecation、Adapter._delegate）。

  • uniqc.test.* 测试套件内部。

  • 任何标注 “internal / experimental / unstable” 的对象。

  • 未在 API 参考中出现的子模块（例如 uniqc._deprecation）。

依赖私有对象等同于自担风险——Hyrum’s Law 不在我们承诺范围内。

当前进入 0.1.0 悬崖的 API 清单

当前 0.1.0 悬崖清单为空。 所有在 0.0.x 期间触发 DeprecationWarning 的公共 API 均已按本政策在 0.1.0 移除， 完整清单见下方“已在 0.1.0 移除的 API”与 0.1.0 迁移指南。

0.1.0 之后的兼容性承诺回归 SemVer 正常规则：未来若在 0.1.x 中引入新的 DeprecationWarning，其移除版本将随弃用条目明确给出（不再默认 0.1.0）。政策框架（公共 API 定义、弃用流程）继续有效。

当前进入 0.2.0 悬崖的 API 清单

以下 API 自新线路可视化引擎（uniqc/visualization/circuit_render/）落地起 进入弃用轨道，将在 0.2.0 移除：

  • uniqc.visualization.draw()（旧行为：委托 pyqpanda3 的 draw_qprog 输出 字符画）→ 迁移：uniqc.visualization.render(circuit, mode="text") 或 Circuit.draw("text")。

  • uniqc.visualization.draw_html()（旧行为：timeline 风格静态 HTML）→ 迁移：render(circuit, mode="html") / Circuit.draw("html")。

  • uniqc.compile.draw（上述 draw 的再导出）→ 迁移：同上。

已在 0.1.0 移除的 API

下列条目在 0.0.x 期间触发 DeprecationWarning，并已在 0.1.0 按本政策移除。逐项的 before/after 对照见 0.1.0 迁移指南：

  • 算法构件的 in-place 旧形式 —— 下列 *_circuit(circuit, ...) 就地突变写法已全部移除，统一收敛为 fragment 形式 *_circuit(n_qubits, ...) -> Circuit，调用方用 circuit.add_circuit(fragment) 组合：

    • qft_circuit(circuit, ...)

    • deutsch_jozsa_circuit(circuit, oracle, ...)

    • dicke_state_circuit(circuit, ...)

    • thermal_state_circuit(circuit, ...)

    • cluster_state(circuit, ...)、ghz_state(circuit, ...)、w_state(circuit, ...)

    • amplitude_estimation_circuit(circuit, oracle, ...)

    • grover_oracle(circuit, marked_state, ...)

    • grover_diffusion(circuit, ...)

    • grover_operator(circuit, oracle, ...)

    • vqd_circuit(circuit, ansatz_params, prev_states, ...)

    以及关键字参数：

    • grover_diffusion(..., ancilla=...) —— 该参数无效果，已删除。

  • uniqc.simulator.get_backend() —— 改用 uniqc.simulator.get_simulator() 或 uniqc.simulator.create_simulator()（参数相同）。顶层 uniqc.get_backend()（云后端工厂）不受影响。

  • IBMAdapter（uniqc.backend_adapter.task.adapters.ibm_adapter） —— 改用 QiskitAdapter（同样基于 qiskit-ibm-runtime，构造签名 proxy= 一致）。ibm_adapter 模块本身保留（其中的标定数据辅助 函数仍被 QiskitAdapter 使用）。

  • 平台原生 task id 查询回退（uniqc.backend_adapter.task_manager） —— 查询接口（query_task / get_platform_task_ids 等）不再把平台 原生 id 经 shard 索引隐式解析到 uqt_* 父任务；请改用提交时返回的 uniqc 内部 task id。显式传入 backend= 的 legacy 直连查询路径不受 影响。shard 索引本身（TaskStore.find_uniqc_id_by_platform_id） 保留。

  • Quafu 平台支持整体移除：quafu_adapter 模块、QuafuBackend、 QuafuCircuitAdapter、QuafuOptions、normalize_quafu、Platform.QUAFU、 CLI / 网关 / 后端发现中的 quafu 分支、quafu.* 配置键，以及 pyquafu 依赖。BAQIS ScQ 芯片的后续支持由 Quark 平台（unified-quantum[quark]） 承接，请迁移到 quark:<chip> 后端标识符。

弃用流程（针对维护者）

引入新的 DeprecationWarning 时，按以下步骤操作：

  1. 使用集中辅助函数：调用 uniqc._deprecation.warn_removed_in_0_1_0()， 不要手写 warnings.warn(..., DeprecationWarning, ...)。 这样所有消息都包含字符串 "uniqc 0.1.0"，方便统一搜索与 迁移工具识别。

  2. 在 docstring 顶部加 .. deprecated:: 指令，写明替代方案。

  3. 在本页“当前进入 0.1.0 悬崖的 API 清单”补一条， 说明何时弃用、替代方案、删除版本（0.1.0 之后必须在条目里明确给出）。

  4. 在 CHANGELOG.md 的 Deprecated 小节登记。

  5. 保留行为不变：除非这次提交是真的把弃用项删掉， 否则不要修改旧路径的可观察行为。

  6. 加测试覆盖弃用警告：用 pytest.warns(DeprecationWarning, match="uniqc 0.1.0") 验证旧路径同时仍然返回正确结果。

不属于弃用的兼容性变更

下列变化 不通过 DeprecationWarning 表达， 而是直接在 CHANGELOG 中以 “Changed” / “Removed” 条目公告：

  • 打包变更：例如 pip install unified-quantum[all] 不再 包含 [quark] 子集。这是包级别的安装契约变更，没有运行时旧 API 入口。

  • 环境变更：Python 版本支持范围、第三方依赖最低版本、平台 wheel 覆盖等。这些以 CHANGELOG + 安装文档为准。

  • 错误信息措辞：异常类型保持兼容，但 str(exc) 不在兼容承诺内。

  • 日志格式：logging / Rich 输出仅供人类阅读，不作机器消费契约。

English summary

UnifiedQuantum follows SemVer 2. Any public API that emits DeprecationWarning during a 0.0.x release is on track to be removed (or its behaviour will no longer be guaranteed compatible) in 0.1.0. There is no compatibility guarantee for deprecated APIs across the 0.0.x → 0.1.0 boundary. Within the 0.0.x line, all currently-deprecated APIs continue to work unchanged.

“Public API” means: anything importable from uniqc.* and documented in the API reference, the uniqc CLI subcommands and options shown in --help, stable HTTP routes under /api/..., and stable keys in ~/.uniqc/config.yaml. Everything under a leading underscore, anything in uniqc.test.*, and anything marked internal/experimental has no compatibility guarantee (Hyrum’s Law does not apply).

Packaging changes (e.g. the contents of the [all] extra) and supported Python versions are announced via the CHANGELOG.md only — they are not DeprecationWarnings but are still subject to clear migration notes.

The full list of APIs removed in 0.1.0 is the bulleted list above (已在 0.1.0 移除的 API); the 0.1.0 cliff list itself is now empty, and post-0.1.0 releases follow normal SemVer guarantees. Newly deprecated in 0.1.x and scheduled for removal in 0.2.0 (see 当前进入 0.2.0 悬崖的 API 清单): uniqc.visualization.draw(), uniqc.visualization.draw_html(), and the uniqc.compile.draw re-export — superseded by uniqc.visualization.render() / Circuit.draw().