AtomUI/docs/engineering/contributing/feature-request-issue-guidelines.md

AtomUI 新特性请求 Issue 规范

本文档定义 AtomUI 新特性请求 Issue 的编写规则。新特性 Issue 应用于提出新增控件能力、扩展 public API、补充主题能力、增加 Gallery 可见示例或改善开发体验的需求。

Bug、回归、崩溃、行为错误和文档错误不使用本文档，应按 BUG Issue 规范 处理。

适用范围

使用本文档的场景：

• 请求新增控件能力。
• 请求扩展 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 标题

标题格式：

[Feature]: <一句话描述新增能力>

标题要求：

• 使用用户能识别的控件、模块或能力名。
• 避免只写内部实现名。
• 避免把方案写得过细，除非 API 方案已经确认。

必填内容

1. 场景

说明真实使用场景和用户目标。

必须回答：

• 谁会使用这个能力。
• 在什么上下文中使用。
• 当前缺口影响了什么工作流。

2. 当前能力

说明当前版本已经能做什么。

必须列出：

• 相关现有 API、事件、属性、文档或 Gallery 示例。
• 是否存在 workaround。
• workaround 的限制。

3. 期望行为

说明新增能力完成后的外部行为。

必须明确：

• 触发时机。
• 成功结果。
• 取消、失败或异常结果。
• 未启用新能力时的默认行为。

4. 建议设计

说明推荐的 API 或设计方向。

要求：

• 优先兼容新增。
• 优先放入已有 options、context、event args 或稳定扩展点。
• 避免为了一个场景增加多个零散参数。
• 复杂输入应使用 context 类型。
• 异步场景应显式使用 task/value task 语义。

5. 行为边界

说明行为顺序、状态流和取消规则。

如果涉及事件或回调，必须说明：

• 旧事件是否仍触发。
• 新回调在旧事件之前还是之后。
• 哪些条件会中止后续流程。
• 重入、重复触发和异步未完成时如何处理。

6. 非目标

明确本次请求不覆盖的内容。

常见非目标：

• 不改变现有默认行为。
• 不移除现有高级用法。
• 不改变无关控件。
• 不改变主题或视觉，除非本需求明确包含视觉变化。
• 不把业务逻辑内置到控件。

7. 兼容性影响

标明兼容级别，并说明判断依据。

兼容级别：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 模板

# [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 路径已补充。