Skip to content

README.md

Latest commit

 

History

History
130 lines (94 loc) · 11.8 KB

README.md

File metadata and controls

130 lines (94 loc) · 11.8 KB
Raw

Specs 方案

specs/ 用于记录复杂需求、重构、公共 API 变更和跨目录修复。组件契约与跨组件工程契约分目录维护，不依赖特定 AI 工具。

组件 A–Z

组件索引：53 个组件目录，按组件规范英文名 A–Z 展示；同组件的不同事项合入一套主文档，共享契约交叉引用。Dialog 的 083 文字槽恢复事项已归入 Dialog 主契约，沿用原事项编号。

非组件 Spec

工程索引：6 份独立契约，分别为 Theme、ThemeController、Golden、Demo、CI 和临时发布门槛。

Theme 的配置职责与 Material 隔离合为一份；Token 运行验证放在该契约的验收文档和 evidence/ 中。索引只描述职责，不代表实现或验收已通过。

什么时候创建 Spec

以下情况建议先创建 Spec：

  • 修改公共组件 API 或行为契约；
  • 组件重构涉及多个文件、状态或交互路径；
  • 需要同时修改组件、示例、测试和站点文档；
  • Bug 根因复杂，或需要明确边界条件和人工验收步骤。

单行文案、格式调整和简单局部修复不要求创建完整 Spec。

「是否需要 Spec」与「是否需要更新日志」是两件独立的事：Spec 看「改动复杂度 / 碰公共契约」（面向开发者），更新日志看「用户感不感知」（面向用户），两者不能互相推导。最容易出错：行为不变的纯内部重构需 Spec（属于重构）但用户无感、不写更新日志——不要因"不写日志"就跳过 Spec。完整判断见 CONTRIBUTING.md「PR 更新日志规范」第 3 条。

标准目录

specs/
├── README.md
├── _template/
├── components/
│   ├── README.md
│   └── 009-Basic-Button/
│       ├── spec.md
│       ├── plan.md
│       ├── tasks.md
│       └── acceptance.md
└── engineering/
    ├── README.md
    ├── 044-Testing-golden-regression/
    ├── 044-ThemeController-import-and-preview/
    ├── 046-Demo-experience/
    ├── 048-Theme-configuration-contracts/
    │   ├── spec.md
    │   ├── plan.md
    │   ├── tasks.md
    │   ├── acceptance.md
    │   └── evidence/
    └── 057-Release-readiness/

命名规则

  • 组件：components/<编号>-<组件分类>-<组件名>/。类别与示例配置一致：Basic、Navigation、Input、DataDisplay、Feedback。组件名保留规范大小写，不带类名前缀 T。组件目录只包含编号、分类、组件名三段，不加事项或 contracts 后缀；具体事项写入主文档章节。
  • 工程：engineering/<编号>-<类别>-<事项描述>/。当前类别为 Theme、ThemeController、Testing、Demo、CI、Release。
  • 编号至少三位，保留历史编号；新增编号取全部 Spec 及正文保留事项编号的最大值加一。历史存在重复编号，引用必须使用完整路径，不按目录展示顺序重编号。

什么时候拆分

  • 职责可以独立说明、独立修改，且有独立验收边界时，才考虑拆成不同 Spec。
  • 总要一起修改、相互依赖才能读懂的内容优先合并；历史任务、PR 或阶段不各自创建一份 Spec。
  • 测试日志、审计表和运行报告是验收证据，不是独立 Spec。必要记录归对应契约的 acceptance.md 与 evidence/；图片与 Golden 按证据保留规则处理，待办状态须保留。

维护规则

  • 一个组件或一项工程职责只维护一套 spec / plan / tasks / acceptance；不同事项按章节合并，已使用的 record-*、source-* 锚点保留用于定位。
  • 多组件契约放在主要责任组件下，跨组件共同遵循的系统规则放在 engineering/；共享内容通过链接复用，不复制。
  • 新增、移动或合并时同步维护所在目录的 README、文档链接、代码中的工具路径和工具根目录定位。证据迁移不刷新原日期、源指纹、SDK 或验收结论。
  • 用户指南与通用文档规范维护在站点和 CONTRIBUTING.md，不单设 Documentation Spec；Testing 只维护 Golden 知识。
  • Release 只暂存尚需候选复核的跨组件门槛，通用发布操作维护在 PUBLISH.md；该轮门槛关闭后可归入发布流程并移除临时 Spec。

操作流程

  1. 先检查组件是否已有入口；已有入口直接更新对应主文档，新组件从 specs/_template/ 在 components/ 下创建 <编号>-<组件分类>-<组件名> 目录；跨组件工程契约在 engineering/ 下创建或复用 <编号>-<类别>-<事项描述> 目录。
  2. 在 spec.md 中写清设计背景、目标与边界、最终方案、关键决策与取舍、兼容性和验收标准；保留影响最终设计的方案演变理由。
  3. 在 plan.md 中记录实现组织、影响范围、落地依赖和验证安排；不复制另一套设计或旧 API 快照。
  4. 在 tasks.md 中集中维护当前任务、未决设计和缺失证据；清理已完成阶段步骤，不在 Spec 标准或验收表中重复维护完成状态。
  5. 实现代码、测试、示例和文档；不要只更新 Spec 而不落地代码。
  6. 在 acceptance.md 中记录实际候选/指纹、环境、执行入口、结论、必要证据与未覆盖范围；不同候选和环境分开，不拼成一次整体通过。
  7. Review 时同时检查实现是否满足 spec.md，以及 Spec 是否准确反映最终实现。
  8. 提交的代码必须与 spec.md 定义的行为契约、验收标准一致；若实现偏离 Spec，需先修订 Spec 再改代码，避免文档与实现长期分叉。
  9. PR 描述「更新日志」小节须与 Spec 描述一致，只记录用户可感知的实际变更（目标受众是用户，非开发者 / 维护者）；内部 / CI / 文档结构调整等用户无需感知的改动不写日志，勾选「本条 PR 不需要纳入 Changelog」；breaking change 使用 breaking commit type，如 - breaking(toast): 调整 xxx 默认行为，会自动归入 Breaking Changes 分组。commit type 与最终分组的对应关系见 CONTRIBUTING.md（tdesign-component/CHANGELOG.md 由 CLI 自动生成，无需人工维护）。

文档边界与正文收敛

文件 维护内容 清理内容
spec.md 背景、目标、方案、关键决策和取舍、最终契约、兼容性、验收标准 重复阶段方案、已取代的当前要求、测试/提交流水
plan.md 当前实现分层、影响范围、依赖顺序、验证安排 旧接口快照、重复设计、已完成排查步骤
tasks.md 当前未完成工作、未决设计与缺失证据 已完成的旧 PR 创建、推送和阶段工作
acceptance.md 有候选和环境边界的验证结论、必要证据、未覆盖项 重复计数、安装与调试流水、无法绑定到候选的整体通过表述

设计演变与取舍

Spec 应解释为什么开发、为什么选择最终方案以及接受了什么代价。保留真正影响设计的备选方案和否决原因，不为补齐模板虚构决策，也不把历史方案原封不动与最终要求并列。实现中发现的新约束或取舍先回写设计，再同步落地。

验收标准与执行结果

  • 标准是可判定的预期行为，不表示已经执行或完成，不使用勾选框维护状态。
  • 实际结果写在 acceptance.md，标注候选完整 SHA/源码指纹、SDK、平台、必要设计依据和操作；结果不等于当前 head 已复验。
  • 缺少唯一候选、日志或平台证据时标记未执行/无法确认，不补造身份，不由旧测试数推断全矩阵通过。多次结果可以摘要，但不能丢掉彼此的范围边界。
  • 原始日志仅保留必要证据入口；图片与 Golden 按下节处理，重复流水不长期堆积。功能、Golden、设计、真机、构建、安装及线上交付分别说明证明范围。
  • 设计不确定与真实未完成事项集中维护在 tasks.md；验收范围引用它，不另建一套状态。清理文档不核销验收门槛。

图片与 Golden 证据

  • 非组件 Spec 不保存页面截图：站点、文档、导航、主题控制器和 CI 等工程事项，以文字结论、候选/环境、复现步骤和必要的结构化记录说明验收，不在 specs/ 中新增或长期保留浏览器、流程或演示截图。
  • 组件视觉优先引用已有 Golden：组件聚焦基线位于 test/components/，公开 Demo 基线位于 example/test/。Spec 记录对应测试文件、基线位置、覆盖场景、执行命令、候选/SDK/平台和结果，不把同一状态的 PNG 再复制进 evidence/。
  • 按实际变化选择证据：组件改动不一定涉及绘制；纯逻辑、回调或生命周期变化用功能测试验证。存在实质视觉变化时，按 Golden 规范检查相应场景；不能因已有初始页面基线，就认定新增或操作后状态已覆盖，也不能因文件存在就声称本次运行通过。
  • 测试资产与 Spec 附件分开：Golden 基线保留在测试目录，实际工具输入保留在所属资源目录，不因清理 Spec 图片删除它们。组件确需保留 Golden 无法表达的独有原始设计依据时，只保留必要原件并说明用途；普通运行截图、拼接图、actual/diff 中间图不作为长期 Spec 附件。
  • 清理同步处理引用：移除截图时更新 Markdown 和机器记录中的附件入口，保留仍有效的观察、候选身份和结果；原图片哈希如需追溯，明确标记为已移除附件的历史标识，不再作为当前文件路径。不借清理刷新旧验证结论或关闭未完成项。

历史附件清理

  • 迁移草稿被现行契约或用户指南取代后，将仍有效的迁移原因并入正文，移除旧调用示例；不靠“历史”标记长期保留冲突用法。
  • PR 拆分、rebase、推送与重复测试流水不长期保存；关键修复原因进入 spec.md，必要检查点、源身份和证据入口进入 acceptance.md。
  • tasks.md 是待办状态的唯一维护位置；冻结运行报告保留当次观察与范围，并链接后续处置，不将旧差异数直接作为当前缺陷数。
  • 原始参考、独有设计裁定和工具实际读取的数据按证据保留规则处理；可复现图片中间产物可以移除，保留输入与生成方式。删除附件前检查 Markdown、机器数据和工具依赖，更新全部引用；不得刷新旧哈希或借清理核销未完成项。

开发记录的保留尺度

Spec保留问题背景、根因、方案及否决理由；acceptance按独立候选/事项保留最后有效结果、环境和未覆盖范围。被后续同范围检查替代的重跑计数、热重载、安装重试、临时路径和PR操作由Git/PR历史追溯。缺少候选或日志的记录只保留有用结论及不确定性，不补造通过证明。真实未决项集中到tasks，不随精简关闭。

图片归档遵循图片与 Golden 证据，不以 Spec 截图重复测试基线。新验收须绑定候选、环境、执行入口和结果，避免重新积累流水。

收敛检查

新增或更新时检查：背景与关键取舍是否保留；最终要求是否仍有旧 API/主题链冲突；计划是否重复正文；旧证据是否绑定范围；未完成项和原有引用是否保留。源码与设计不一致但没有裁定依据时明确列出待核对，不擅自以旧截图或当前实现代替最终决策。