mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-29 07:16:33 +08:00
262 lines
8.0 KiB
Markdown
262 lines
8.0 KiB
Markdown
# 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 不改变的现有行为。>
|
||
|
||
## 兼容性影响
|
||
|
||
兼容级别：<L1 / L2 / L3>
|
||
|
||
<说明是否影响 public API、默认行为、主题、Gallery、AOT 或迁移成本。>
|
||
|
||
## 验收标准
|
||
|
||
- [ ] <可测试条件和期望结果。>
|
||
- [ ] <可测试条件和期望结果。>
|
||
- [ ] <文档、Gallery 或测试要求。>
|
||
|
||
## 关联材料
|
||
|
||
- 源码：`<path>`
|
||
- 文档：`<path>`
|
||
- Gallery：`<path>`
|
||
- 讨论：`<link or issue>`
|
||
```
|
||
|
||
## 控件类新特性附加要求
|
||
|
||
控件类新特性必须补充以下判断：
|
||
|
||
- 是否新增 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 路径已补充。
|