# AtomUI 新特性请求 Issue 规范 本文档定义 AtomUI 新特性请求 Issue 的编写规则。新特性 Issue 应用于提出新增控件能力、扩展 public API、补充主题能力、增加 Gallery 可见示例或改善开发体验的需求。 Bug、回归、崩溃、行为错误和文档错误不使用本文档，应按 [BUG Issue 规范](bug-issue-guidelines.md) 处理。 ## 适用范围 使用本文档的场景： - 请求新增控件能力。 - 请求扩展 public/protected API。 - 请求新增 Avalonia property、event、command、template part、pseudo-class、token 或 theme entry。 - 请求补充 Gallery 示例、文档入口或静态 API 使用方式。 - 请求把现有 workaround 提升为正式支持能力。 不使用本文档的场景： - 已有 API 行为错误。 - 运行时异常、崩溃、资源泄漏或 AOT 发布失败。 - 文档内容错误或示例代码无法运行。 - 单纯咨询用法。 ## 编写原则 - 先写用户场景，再写 API 方案。 - 说明当前能力和限制，不把已有 workaround 描述成完全不支持。 - 期望行为必须可验证。 - API 建议必须标明兼容性影响。 - 行为变更必须说明事件顺序、状态流或取消语义。 - 控件类特性必须说明 Gallery、文档、测试和 AOT 影响。 - 范围要收敛，明确非目标。 ## Issue 标题 标题格式： ```markdown [Feature]: <一句话描述新增能力> ``` 标题要求： - 使用用户能识别的控件、模块或能力名。 - 避免只写内部实现名。 - 避免把方案写得过细，除非 API 方案已经确认。 ## 必填内容 ### 1. 场景 说明真实使用场景和用户目标。 必须回答： - 谁会使用这个能力。 - 在什么上下文中使用。 - 当前缺口影响了什么工作流。 ### 2. 当前能力 说明当前版本已经能做什么。 必须列出： - 相关现有 API、事件、属性、文档或 Gallery 示例。 - 是否存在 workaround。 - workaround 的限制。 ### 3. 期望行为 说明新增能力完成后的外部行为。 必须明确： - 触发时机。 - 成功结果。 - 取消、失败或异常结果。 - 未启用新能力时的默认行为。 ### 4. 建议设计 说明推荐的 API 或设计方向。 要求： - 优先兼容新增。 - 优先放入已有 options、context、event args 或稳定扩展点。 - 避免为了一个场景增加多个零散参数。 - 复杂输入应使用 context 类型。 - 异步场景应显式使用 task/value task 语义。 ### 5. 行为边界 说明行为顺序、状态流和取消规则。 如果涉及事件或回调，必须说明： - 旧事件是否仍触发。 - 新回调在旧事件之前还是之后。 - 哪些条件会中止后续流程。 - 重入、重复触发和异步未完成时如何处理。 ### 6. 非目标 明确本次请求不覆盖的内容。 常见非目标： - 不改变现有默认行为。 - 不移除现有高级用法。 - 不改变无关控件。 - 不改变主题或视觉，除非本需求明确包含视觉变化。 - 不把业务逻辑内置到控件。 ### 7. 兼容性影响 标明兼容级别，并说明判断依据。 ```markdown 兼容级别：L1 / L2 / L3 ``` 兼容级别定义如下： | 级别 | 含义 | 典型范围 | Issue 必填信息 | 处理要求 | | --- | --- | --- | --- | --- | | `L1` | 兼容新增 | 新增 public API、Avalonia property、event、command、context 类型、options 字段、token、template part、Gallery 示例或文档；未启用新能力时既有行为不变。 | 新 API 的默认值、nullability、触发时机、是否影响布局/渲染/状态流、文档和测试范围。 | 默认可作为普通 minor/feature 处理，但仍需测试默认行为不变。 | | `L2` | 可观察语义变更 | 改变默认值、事件触发顺序、回调时机、状态优先级、键盘/鼠标交互、焦点行为、popup/window 生命周期、视觉状态或 Gallery 可观察行为。 | 变更前后行为差异、受影响场景、迁移建议、为什么不能用 L1 兼容新增解决。 | 必须由维护者明确确认，测试要覆盖旧行为差异和新行为。 | | `L3` | 破坏性变更 | 删除、重命名或改变 public/protected API 类型；改变 enum 值语义；移除支持用法；删除或重命名 template part、pseudo-class、token、resource key、ControlTheme key；破坏 XAML 或二进制兼容。 | 破坏范围、迁移方案、替代 API、版本策略、是否需要 major 版本。 | 默认不接受，除非明确批准并给出迁移计划。 | 判断规则： - 未启用新能力时所有既有调用、XAML、主题和 Gallery 行为保持不变，才可标为 `L1`。 - 只要改变用户可观察行为，即使 API 仍兼容，也应标为 `L2`。 - 只要会让既有源码、XAML、主题资源或二进制引用失效，应标为 `L3`。 - 无法确定时，先按更高风险级别标注，并在 Issue 中说明不确定点。 如果不是 `L1`，Issue 必须说明迁移影响、替代方案和为什么不能用兼容新增完成。 ### 8. 验收标准 验收标准必须可测试。 每条验收标准应包含： - 输入条件。 - 触发动作。 - 期望结果。 必须覆盖： - 默认行为保持不变。 - 新能力启用后的成功路径。 - 新能力启用后的取消或失败路径。 - 主要宿主、平台或交互入口。 - 文档或 Gallery 更新要求。 ### 9. 关联材料 列出相关上下文。 可包含： - 相关源码路径。 - 相关设计文档路径。 - 相关 Gallery 页面。 - 相关讨论、截图或 issue。 - 当前版本信息。 ## Markdown 模板 ```markdown # [Feature]: <一句话描述新增能力> ## 场景 <描述真实使用场景和用户目标。> ## 当前能力 <说明当前已有 API、事件、属性、文档或 workaround。> ## 当前限制 <说明当前方式为什么不够直观、不够完整或不能覆盖目标场景。> ## 期望行为 <说明新增能力完成后的外部行为、默认行为、取消行为和异常行为。> ## 建议设计 <说明推荐 API、options、context、event args、状态流或扩展点。> ## 行为边界 <说明事件顺序、取消语义、异步处理、重入处理和状态归一规则。> ## 非目标 - <本 Issue 不解决的范围。> - <本 Issue 不改变的现有行为。> ## 兼容性影响 兼容级别： <说明是否影响 public API、默认行为、主题、Gallery、AOT 或迁移成本。> ## 验收标准 - [ ] <可测试条件和期望结果。> - [ ] <可测试条件和期望结果。> - [ ] <文档、Gallery 或测试要求。> ## 关联材料 - 源码：`` - 文档：`` - Gallery：`` - 讨论：`` ``` ## 控件类新特性附加要求 控件类新特性必须补充以下判断： - 是否新增 public/protected API。 - 是否新增 Avalonia property、event、command、template part、pseudo-class 或 token。 - 是否改变默认值、事件时机、状态流、焦点、键盘、pointer 或 popup/window 行为。 - 是否影响 ControlTheme、资源 key、token resource key 或 Gallery 展示。 - 是否涉及 AOT、trimming、反射、动态注册或 source generator。 - 是否需要更新控件设计文档、实现文档、token 文档或 changelog。 ## 维护者评审清单 评审新特性 Issue 时检查： - 场景是否真实且足够具体。 - 当前能力和限制是否准确。 - 建议设计是否过度指定实现。 - 是否存在更小的兼容新增方案。 - 是否能复用现有控件模式。 - 是否需要补充设计文档。 - 是否需要 Gallery 示例。 - 是否需要 AOT 验证。 - 验收标准是否能转成自动化测试或明确的手动验证。 ## 提交前检查清单 - [ ] 标题能独立说明需求。 - [ ] 场景不是单纯“希望加 API”。 - [ ] 当前能力和 workaround 已说明。 - [ ] 当前限制已说明。 - [ ] 期望行为可验证。 - [ ] 行为边界包含取消、失败和默认行为。 - [ ] 非目标已列出。 - [ ] 兼容级别已标注。 - [ ] 验收标准可转成测试。 - [ ] 相关源码、文档或 Gallery 路径已补充。