Skip to content

FEATURE_DEVELOPMENT.md

Latest commit

 

History

History
96 lines (71 loc) · 8.93 KB

FEATURE_DEVELOPMENT.md

File metadata and controls

96 lines (71 loc) · 8.93 KB
Raw

新功能开发规范

适用范围

本规范适用于无线麦SayAll.app 仓库中的所有新功能开发，包括仓库作者、维护者、外部贡献者、自动化 Agent 和受委托的开发者。任何人都不能因为是功能提出者、仓库所有者或维护者而跳过本规范。

本文件是新功能从立项到 PR 的统一流程入口。它只拥有新功能的查重、范围、实现和验证流程；分支、提交与合并以 BRANCH_MANAGEMENT.md 为准，仓库级硬门禁以 AGENTS.md 为准，具体产品行为以对应功能的 PRODUCT_SPEC.md 和适用的跨平台专项合同为准，提交 PR 时还必须完成 PR 提交模板 中的新功能检查项。发现互斥规则时不得简单叠加“更严格的一项”，必须按 AGENTS.md 的规范层级在独立治理 PR 中消除冲突。

开发前检查

  1. 执行 git fetch origin main，记录最新 origin/main 的完整 SHA。新功能必须从该 Commit 创建独立分支和持久化 worktree，不得基于旧功能分支、其他未合入 PR、release-main 或本地过期的 main 直接开发。
  2. 扫描全部 Open PR（含 Draft）的标题和标签。按关键词、模块和路径筛选相关候选，再查看候选描述、文件和必要 Diff。不能只根据标题判定候选无重复；证据不足时扩大检查。
  3. 同时检查最新 origin/main 的代码、测试和 TODO.md，确认功能没有已经实现、已经被替代或已经明确不做。
  4. 如果发现重叠 PR，优先在已有 PR 上协作、补充或重新基于最新主线接续；未经维护者明确决定，不得再创建一个功能相同的 PR。PR 描述必须列出查重结果和相关 PR 链接。
  5. 明确本次功能的用户目标、范围、不做事项、受影响模块、兼容边界和验证方式。一个 PR 只承载一个可独立审查的功能，不得混入无关重构、清理或其他功能。

推荐使用以下命令完成基础查重：

git fetch origin main
git rev-parse origin/main
gh pr list --state open --limit 200

分支与主线同步

G-MAIN.reference=BRANCH_MANAGEMENT.md
  • 分支、worktree、提交、PR 目标和 Hotfix 例外必须遵守 BRANCH_MANAGEMENT.md。普通新功能 PR 的目标分支只能是 main。
  • 开发开始时必须基于最新 origin/main。创建 PR 前再次 fetch；如果主线前进，检查新增 diff、冲突及共享依赖影响。存在相关变化时同步主线并重新运行受影响验证；无关且无冲突时，记录最新 SHA 和判断依据即可。发布仍锁定精确主线。
  • 不得用旧分支整体覆盖主线，也不得为了减少冲突绕过当前架构、测试或产品规范。
  • PR 合入前必须确认变更仍然只包含本功能，并且没有夹带其他 worktree 或用户未提交的修改。

实现边界

  • 使用当前主线已有架构和模式，只增加完成该功能所必需的代码、测试、日志、文档和资源；不得进行投机性抽象或顺手重构。
  • 不允许读取、解析、解密、复制或依赖任何第三方 App 的私有文件、数据库、沙盒容器、历史记录、私有运行库、私有协议或未公开数据格式。用户授权、签名包、Helper、测试环境和本机可访问都不能放宽此边界。
  • 第三方 App 集成只能使用公开 API、公开协议、用户可见的辅助功能界面或用户明确选择的文件。无法通过公开边界实现时，应停止该方案并在 PR 中说明，而不是增加绕过路径。
  • 新增或修改功能必须遵守 LOGGING.md，日志覆盖从请求入口到最终用户结果的完整链路，并保持脱敏、可关联、可去重和可归因。
  • 检查 TODO.md 是否有对应项目；只有功能实现并完成相应验证后，才能在同一 PR 中更新为完成。
  • 面向用户的全新功能必须在 Testing/ 下新增或更新测试手册。涉及硬件时还必须遵守 Testing/HardwareCompatibilityContract.md；涉及 Onboarding 时必须遵守 feature/first-run-onboarding/PRODUCT_SPEC.md 及其平台附件。
  • 修改共享协议、持久化、音频、HID、按键或 Feature Flag 时，必须验证旧版本、默认关闭、异常恢复及稳定主路径，不得用开关默认关闭代替回归验证。

UI 变更截图门禁

只要新功能新增或修改用户可见页面、面板、窗口、状态卡、导航、控件、文案布局或交互状态，PR 描述或评论中就必须附带实际运行截图。没有截图的 UI 新功能 PR 不得进入合入评审。

截图必须满足以下要求：

  • 来自本次 Commit 构建的生产 UI 和真实运行页面，不得使用设计稿、重绘图、仅截代码、孤立的替代视图或“已经检查通过”的文字声明代替。
  • 覆盖所有受影响页面和关键状态，至少包含中文浅色与中文深色；英文或其他语言会改变布局时，也必须覆盖对应语言。
  • 在产品默认窗口尺寸和最小支持尺寸下验证；使用 screenshot harness 的压力截图必须与真实窗口运行截图分开标注。
  • 在 PR 中标明截图对应的 Commit、App 版本或构建、窗口尺寸、外观和生成方式，并直接附为 GitHub 可访问的图片或持久化证据链接。只提供他人无法访问的本地路径不算完成。
  • 截图、设计稿和界面录制的图片字节不进入版本控制；需要长期留档时，按 AGENTS.md 的「截图与设计稿归档规范」在 Screenshots/<batch>/manifest.json 记录索引、尺寸、SHA-256 和外部 URL。向 Screenshots/、Design/ 等非构建位置新增位图或视频会被 Repository governance 直接拒绝。
  • 截图不得包含用户内容、个人信息、设备身份、路径、凭据或第三方 App 私有状态，应使用脱敏测试数据。
  • 截图只能证明静态 UI。真实硬件、系统权限、音频、前后台状态和第三方 App 行为仍须按测试手册验证，并在 PR 中明确未覆盖边界。
  • Onboarding 变更按 AGENTS.md 的风险分类和生产清单执行专项回归；流程或共享布局变化仍要求完整页面截图，不能以局部截图替代。

测试与交付

  • 自动化测试必须覆盖核心成功路径，以及受影响的失败、取消、超时、重试和恢复路径。构建通过不能替代功能验证。
  • 涉及真实遥控器、蓝牙、音频、系统权限或第三方 App 的功能，必须分别说明自动化、本机代理和用户实测的结果；没有实机证据时只能标记为待验证或候选。
  • macOS 本地运行 swift build、swift test 或 swift package resolve 时必须传入 --disable-keychain。
  • 提交前至少执行与变更相称的测试、git diff --check 和 Markdown 链接检查。不得把测试未运行写成通过。

PR 提交与审查

G-CI.reference=BRANCH_MANAGEMENT.md

新功能 PR 必须使用 PR 提交模板，并在描述中包含：

  1. 用户问题、功能目标、范围和明确不做事项。
  2. 开发起点的 origin/main 完整 SHA，以及提交前再次检查主线的结果和同步决定。
  3. Open PR 查重结果、检索日期和所有相关 PR 链接。
  4. 修改的模块和每个文件存在的必要性。
  5. 自动化、构建、日志、截图、真实设备和第三方流程的验证结果与边界。
  6. 兼容性、隐私、数据迁移、回滚和已知风险。
  7. UI 变更对应的实际运行截图；没有 UI 变更时明确写明不适用。

适用的本地验证未完成、截图未补齐或必要真实环境仍在等待时，PR 必须保持 Draft。只有 CI 结果或等待被用户明确豁免时，按 BRANCH_MANAGEMENT.md 的“用户明确授权的 CI 例外”执行，其他门禁不变。CI 全部通过不代表满足本规范；维护者仍需核对查重、隐私边界、实际截图和真实环境证据。

合入前检查清单

  • 功能从最新 origin/main 开始，提交 PR 前已检查最新主线，并按影响决定同步和验证。
  • 已扫描全部 Open PR 的标题和标签，并详细检查相关候选，记录筛选依据和相关链接。
  • PR 只包含一个新功能和直接必要的修改。
  • 未读取或依赖任何第三方 App 的私有文件、数据或协议。
  • 已同步必要的日志、测试手册、TODO.md 和专项产品规范。
  • UI 变更已在 PR 附件或持久链接中附实际运行截图，并覆盖必要语言、外观、尺寸和状态。
  • 未向仓库提交截图、设计稿或界面录制的图片字节；需要留档时只新增 manifest.json 索引。
  • 已区分自动化结果、截图证据、代理实测和真实用户/硬件验收边界。
  • PR 描述已完整填写，未完成项目保持 Draft，目标分支为 main。