算子变更影响与迁移说明模板
本模板用于记录会影响算子使用者、调用方或部署环境的变更。典型场景包括接口调整、支持范围变化、输出语义变化、安装路径变化、弃用旧入口和修复可能改变结果的缺陷。
何时需要
出现以下任一情况时，建议在 PR 描述或算子文档中附迁移说明：
- 输入、输出或属性的名称、顺序、必选性、类型、shape、默认值发生变化。
- 可选输出、错误处理、数值精度、排序或确定性行为发生变化。
- ACLNN、PyTorch Extension 或其他公开调用入口发生变化。
- 支持的芯片、CANN 版本、format、动态 shape 范围发生变化。
- 构建命令、安装包、vendor 路径或环境变量发生变化。
- 旧能力被弃用、替换或移除。
仅内部重构且公开行为、构建安装和性能口径均不变时，可以不填写完整模板，但应在 PR 中明确“无用户可见变化”及其验证依据。
兼容性分类
| 分类 | 定义 | 示例 |
|---|---|---|
compatible |
旧调用无需修改，结果语义和部署方式保持兼容 | 新增可选属性且默认值保持旧行为 |
behavior-change |
调用仍可运行，但结果、错误处理或性能特征可能变化 | 修复排序、舍入、异常输入处理 |
migration-required |
用户需要修改调用、配置、构建或部署步骤 | 参数重命名、输出顺序调整、安装路径变化 |
deprecated |
旧入口仍可用，但已计划移除 | 提供新 API，同时保留旧 wrapper |
removed |
旧入口或能力已不可用 | 删除旧 API、dtype 或芯片支持 |
不能确定兼容性时标记为“待确认”，不要默认写成兼容。
模板正文
# `<operator_name>` 变更影响与迁移说明
## 变更概览
| 项目 | 内容 |
| --- | --- |
| 关联 PR / Issue | `<链接或编号>` |
| 变更类型 | `<接口 / 行为 / 支持范围 / 构建安装 / 弃用 / 缺陷修复>` |
| 兼容性分类 | `<compatible / behavior-change / migration-required / deprecated / removed>` |
| 影响版本或 Commit | `<version / sha>` |
| 目标用户 | `<Python / ACLNN C++ / 直调 / 部署维护者 / 全部>` |
用 2-3 句话说明为什么需要本次变更，以及使用者是否必须采取操作。
## 影响范围
| 接口面 | 是否影响 | 说明 |
| --- | --- | --- |
| 输入 / 输出 | `<是 / 否>` | `<名称、顺序、数量、必选性>` |
| dtype / format | `<是 / 否>` | `<新增、移除或行为变化>` |
| shape / rank | `<是 / 否>` | `<动态范围、边界和推导关系>` |
| 属性 | `<是 / 否>` | `<类型、默认值和值域>` |
| 数值或结果语义 | `<是 / 否>` | `<精度、排序、确定性、有效区间>` |
| ACLNN 接口 | `<是 / 否>` | `<函数名和参数>` |
| Python / PyTorch 接口 | `<是 / 否>` | `<函数名、参数和返回值>` |
| 芯片 / CANN | `<是 / 否>` | `<支持范围>` |
| 构建 / 安装 | `<是 / 否>` | `<命令、包名、路径和环境变量>` |
| 性能特征 | `<是 / 否>` | `<仅说明已验证变化，不填写推测>` |
## 变更前后对照
### 接口或配置
| 项目 | 变更前 | 变更后 | 兼容性影响 |
| --- | --- | --- | --- |
| `<parameter / output / command>` | `<old>` | `<new>` | `<impact>` |
### 行为
| 场景 | 变更前 | 变更后 | 用户需要关注 |
| --- | --- | --- | --- |
| `<boundary / special value / optional output>` | `<old behavior>` | `<new behavior>` | `<action or none>` |
所有描述应来自代码、测试或文档证据。无法验证的行为标记为“待验证”。
## 用户迁移步骤
### 调用代码
变更前：
```python
<old call>
```
变更后：
```python
<new call>
```
### 构建或安装
```bash
# 变更前
<old command>
# 变更后
<new command>
```
### 配置或环境变量
| 旧配置 | 新配置 | 操作 |
| --- | --- | --- |
| `<old>` | `<new>` | `<add / replace / remove>` |
如果无需用户迁移，写明：
```text
无需修改调用或部署步骤；默认行为保持兼容。
```
并列出验证该结论的测试或对照证据。
## 弃用与移除计划（可选）
| 项目 | 内容 |
| --- | --- |
| 弃用入口 | `<API / attribute / path>` |
| 替代入口 | `<replacement>` |
| 弃用开始 | `<version / date / commit>` |
| 计划移除 | `<version / date；未确定则写待定>` |
| 过渡期行为 | `<warning / alias / compatibility wrapper>` |
不要承诺未经维护者确认的发布日期。
## 回滚方案
- 回滚条件：`<哪些失败或兼容问题触发回滚>`
- 回滚方式：`<revert commit / 恢复旧包 / 切换旧接口>`
- 数据或产物兼容：`<是否需要清理缓存、重装包或恢复配置>`
- 回滚验证：`<命令和预期结果>`
如果变更不可安全回滚，必须说明原因和替代恢复方式。
## 验证证据
| 验证项 | 命令 / 用例 | 结果 | 证据 |
| --- | --- | --- | --- |
| 旧调用兼容性 | `<command>` | `<PASS / FAIL / NOT_RUN>` | `<summary>` |
| 新调用正确性 | `<command>` | `<PASS / FAIL / NOT_RUN>` | `<summary>` |
| 边界与异常输入 | `<command>` | `<PASS / FAIL / NOT_RUN>` | `<summary>` |
| 安装 / 升级 | `<command>` | `<PASS / FAIL / NOT_RUN>` | `<summary>` |
| 回滚 | `<command>` | `<PASS / FAIL / NOT_RUN>` | `<summary>` |
没有 NPU 或目标环境时，使用 `NOT_RUN` 并说明原因，不要写成通过。
## 已知限制与未解决问题
- `<未覆盖平台、尚未迁移入口、兼容层限制或后续 Issue>`
## 面向发布说明的摘要
```text
<一句话说明用户可见变化>
迁移动作：<无需操作 / 需要修改调用 / 需要重新安装>
兼容性：<classification>
```
提交前检查
- 兼容性分类与实际用户动作一致。
- 旧行为和新行为均有可定位的代码、测试或文档依据。
- 所有受影响的公开入口、输出语义和安装方式均已覆盖。
- 迁移步骤可以从干净环境执行，不包含本地绝对路径。
- 弃用时间线经过维护者确认；未确认的日期标记为待定。
- 回滚方案包含触发条件、操作和验证。
- 未执行验证项明确标记为
NOT_RUN。 - 文档不包含账号、令牌、设备地址、私有数据或内部链接。