修订记录
| 修订版本 | 修订人 | 修订日期 | 修订内容 | 审核日期 |
|---|---|---|---|---|
| V1.0 | pengqiang-gs | 2025/09/03 | 建立规范初稿 | |
| V1.1 | pengqiang-gs | 2025/10/27 | 增加接口变更发布流程 |
接口变更范围
本规范看护责任主体为 interface SIG，规范主要针对对于 openUBMC 的接口变更进行流程规范化处理。具体涉及的接口以及变更的项有：
- 北向接口：通过不同的网络协议或者配置对于BMC进行管理的接口，具体有：
(1) Redfish 接口：接口的请求（参数个数，参数类型），响应（参数个数，参数类型），权限
(2) WEB UX 接口（交互界面）：UX元素个数，类型，权限，样式
(3) CLI 接口（SSH或者串口登陆交互界面）：命令参数，执行权限，回显内容
(4) UIRest 接口：接口的请求（参数个数，参数类型），响应（参数个数，参数类型），权限
(5) SNMP 接口：接口的请求（参数个数，参数类型），响应（参数个数，参数类型），权限
(6) IPMI 接口：接口的请求（参数个数，参数类型），响应（参数个数，参数类型），权限 - 配置项接口：通过配置文件进行BMC配置管理的接口，具体有：
(1) 配置导入导出接口：配置项的类型，导入导出行为
(2) 定制化项接口：定制化项的类型，校验方式 - 资源协作接口：通过 DBus 协议暴露出来的开发资源接口，具体有：
(1) DBus 资源协作接口（整体）：一般是接口下的属性或者方法变更
(2) 资源协作接口属性：属性名称，属性签名/类型，读写类型/权限，变更信号，持久化方式
(3) 资源协作接口方法：方法名称，方法权限，方法请求签名/参数，方法响应签名/参数，返回错误标识
(4) 资源协作接口信号：信号名称，信号参数签名 - 错误引擎：采用标准（Redfish Specification #2065）或者自定义的错误消息。具体有：
(1) 标准错误：不允许变更
(2) 自定义错误：错误名称，Message，Resolution，Suggestion，HTTPCode，IPMIcompletionCode，SNMPCode
接口变更流程
接口通用变更流程
- 第一步：开发者在社区 “Interface SIG + Interface评审” 板块下新建话题，创建评审议题
- 第二步：Interface SIG 定期组织评审会议评审议题，给出是否需要发变更声明的意见
- 第三步：对于不需要发变更声明则进行议题结论刷新归档即可；对于需要发变更声明的话题，需要记录遗留问题并且发布接口变更声明之后再行刷新结论
接口废弃变更流程
- 第一步：开发者在社区 “Interface SIG + Interface评审” 板块下新建话题，创建评审议题
- 第二步： Interface SIG 定期组织评审会议评审议题，给出是否允许废弃的决策意见
- 第三步：对于不允许废弃的接口则进行议题结论刷新归档即可；对于需要废弃的接口议题，需要记录遗留问题并且发布接口变更声明（废弃，需要明确废弃截止版本，使用since或者until关键字）之后再行刷新结论
变更流程示意图如下：
graph TD
subgraph 接口评审
choice1{是否需要接口废弃/变更}
申报议题 --> 议题预审
议题预审 --> SIG例会评审
SIG例会评审 --> choice1
choice1 --> |是|申报接口废弃/变更
申报接口废弃/变更-->接口废弃/变更审核
接口废弃/变更审核 --> 接口废弃/变更发布
接口废弃/变更发布 --> 刷新评审结论
choice1 --> |否|刷新评审结论
刷新评审结论 --> 议题关闭归档
end
subgraph 版本发布
choice2{是否有接口废弃/变更}
版本发布评审 --> choice2
choice2 -->|否|版本ReleaseNote
choice2 -->|是|接口废弃/变更发布
接口废弃/变更发布 --> |提取|变更内容
变更内容 --> |填充|版本ReleaseNote
end
参考资料
- 北向接口变更声明样例：【变更声明】Redfish接口SimpleUpdate带有清除配置升级权限变更
- 资源协作接口变更声明样例：【变更声明】资源协作接口 FirmwareMatchRules 权限和签名变更