AI Coding Kit

主题

📄 本页由源文件 rules/按需-更新日志编写规范.mdc 自动投影生成（单一权威源）。请勿直接编辑本页。

按需-更新日志编写规范 ​

触发时机：撰写或修订项目 changelog.md（或同类版本更新说明）时。 核心：日志面向使用者，只回答「哪个组件、发生了什么、我要不要动代码」。

1. 描述方式：概括式 ​

  • 一条一句话，只写「改了什么 + 影响」；根因、算法、实现手段不写进日志
  • 「一句话」指概括方式（不展开根因与实现细节），不是「一句里塞多件事」—— 一条只讲一个主题
  • ❌ 定位尺寸改用 offsetWidth / offsetHeight，因为 transform 会让 getBoundingClientRect 返回缩放后的视觉尺寸
  • ✅ 修复缩放动画期间位置错位
  • 根因、取舍与实现细节归 commit message / PR 描述
  • 边界：「实现细节」指内部构建 / 脚本 / 测试 / 重构等使用者不可感知的改动；docs/ 与 development/ 的内容更新不属于此列，必须入日志（写法见 §2、§3）

2. 合并同源、拆开异源 ​

  • 同一组件、同一工具函数族、同一能力主题的多个改动 → 合并为一条
  • ❌ Tooltip 定位一条 + Tooltip 交互一条
  • ✅ Tooltip 定位与交互合并为一条
  • ❌ 一条里混入多个不相关主题（如「新增属性 + 修复失焦 + 构建产物调整」）—— 读者无法判断其中哪句与自己相关
  • 合并的对象是「同源改动」，不是「为控制条数而压缩」；不同源就拆开，宁可条数多也不要堆叠
  • 无信息量的兜底条目（如「组件库及文档代码优化」）不写 —— 但不是省略文档更新：docs/（面向使用者）与 development/（面向贡献者）的内容更新都要入日志，需写明「哪篇 / 哪份说明变了、变成什么」；受众不同的文档更新各自成条（如使用者文档 docs/＋README 一条、贡献者文档 development/＋CONTRIBUTING 一条），禁止的只是「优化文档」这类一句打包写法

3. 保留必要信息（不得过度概括） ​

以下必须写清，压缩到看不出影响即不合格：

场景要求
破坏性变更保留 ⚠️ **破坏性变更** 前缀，写明「移除了什么 / 改用什么」
默认值变化写明旧值 → 新值
需用户改代码写明替代写法
文档更新docs/ / README / development/ / CONTRIBUTING 的内容更新须写明「哪篇文档变了、读者要注意什么」，按受众拆条；不写「优化文档」这类打包表述

4. 格式约定 ​

  • 每条以动词开头：新增 / 优化 / 增强 / 修复 / 重构
  • 组件与工具函数名用 Markdown 链接指向文档，如 [文字提示 Tooltip](/guide/components/tooltip.html)
  • 属性名、API、全局对象等用行内代码包裹
  • 条目数不设上限：由改动量自然决定 —— 架构重构、批量破坏性变更的大版本条目自然多，小版本自然少
  • 不为凑数拆分（一件事写成多条），也不为控数堆叠或删减信息（多件事挤进一条、砍掉必要语义）
  • 每条长度以「一句话可读」为准；若一条读下来需要逐句分辨主题，说明该拆条了

5. 版本与历史 ​

  • 已发布版本的历史条目默认不回改，用户明确要求时才回改
  • 新版本严格按本规范撰写，不因历史风格而妥协

6. 自检清单 ​

  • [ ] 每条能否一句话说清「改了什么 + 影响」？
  • [ ] 同组件 / 同工具函数族 / 同能力主题的条目是否已合并？
  • [ ] 是否存在「一条堆叠多个不相关主题」的情况？应拆为多条
  • [ ] 破坏性变更、默认值变化是否写明替代用法？
  • [ ] 是否残留根因、算法、内部函数名等实现细节？
  • [ ] docs/ / README / development/ / CONTRIBUTING 的内容更新是否已入日志（按受众拆条，不是「优化文档」这类打包写法）？
  • [ ] 无信息量的条目是否已删除？
  • [ ] 是否为了控制条数而删减或模糊了必要信息？（条目数不是压缩目标）

基于「单一权威源」哲学构建 —— 文档由源文件投影生成

AI Coding Kit