📄 本页由源文件
rules/按需-更新日志编写规范.mdc自动投影生成（单一权威源）。请勿直接编辑本页。
按需-更新日志编写规范
触发时机：撰写或修订项目
changelog.md（或同类版本更新说明）时。 核心：日志面向使用者，只回答「哪个组件、发生了什么、我要不要动代码」。 2026-10-26 对标主流组件库日志重构：借鉴「一条一现象」的条目粒度，新增 §1.2 长度上限、§4.1 条目顺序（不设分类小节，实测本项目多数版本 1–5 条，小节标题过重）、§4.2 冗余词、§4.3 issue 关联、§9 反模式清单。
1. 描述方式：概括式
- 落笔前先过「读者决策测试」：这句能否改变读者的某个决定（要不要改代码 / 要不要覆盖某个变量 / 会不会踩到）？不能就删 —— 尤其警惕为满足 §3「必须写清」而补的括号：默认值未变、新功能的默认行为、取值关系（
取 A 的浅一档、按尺寸取 small 档）一律不补 - 一条一句话，只写「改了什么 + 影响」；根因、算法、实现手段不写进日志
- 「一句话」指概括方式（不展开根因与实现细节），不是「一句里塞多件事」
- ❌
定位尺寸改用 offsetWidth / offsetHeight，因为 transform 会让 getBoundingClientRect 返回缩放后的视觉尺寸 - ✅
修复缩放动画期间位置错位 - 表述落到结果层：需要读者理解内部机制才读懂的写法必须改写（❌
坏键不再中断回调，其余组件主题色恢复更新→ ✅坏键改为忽略并告警） - 不复述未变化的取值：默认值 / 默认行为没变时，不写「未传入时仍跟随 X（X + 24）」这类取值细节，只写「修复 X 属性不生效的问题」
- 根因、取舍与实现细节归 commit message / PR 描述
- 边界：「实现细节」指内部构建 / 脚本 / 测试 / 重构等使用者不可感知的改动；
docs/与development/的内容更新不属于此列，必须入日志（写法见 §2、§3）
1.1 细节颗粒：留锚点，删症状
- 必须保留检索锚点：属性 / 事件 / 方法 / 插槽 /
CSS变量名（如start()、interval、itemStyle）——读者靠它们在自研代码里对号，删了就无法判断是否波及自己 - 症状不复述：同一问题能观察到的多个症状不逐条列，最多留一句最有辨识度的
- ❌
重复调用 start() 会叠加（越滚越快、stop() 停不下来），KeepAlive 失活后仍在推进、返回时已跳到其他条目，卸载后残留定时器 - ✅
垂直滚动的启停：start() 重复调用与卸载后调用不再叠加滚动、KeepAlive 失活即暂停
- ❌
- 症状白描属「读者本就知道的表象」，锚点与影响属「读者尚未掌握的信息」，篇幅优先给后者
1.2 长度上限（2026-10-26 新增）
- 单条 ≤ 120 字（不含 Markdown 链接与行内代码），超过先按 §2 判断能否合并，不能合并再按「读者是否要做不同动作」拆条
- 判据：一条里出现 ≥3 个分号分句，通常说明装了多个主题，必须拆
- 一个版本块超过 15 条时，回头检查是否存在同主题可合并项（历史最长条目 670 字、单块 16 条，均属超载）
2. 合并同源、拆开异源
- 判定顺序：先合并，再拆分 —— 同一组件、同一工具函数族、同一能力主题的多个改动默认合并为一条（主句概括 + 括号 / 分句承接具体结果）；仅当合并后一条里仍有不相关主题时，才拆开
- 条目数 ≈ 主题数，不是症状数：同一组件的多个修复落在同一主题（滚动行为 / 表单校验 / 样式属性 / 主题变量…）就只写一条；补丁版本只动一个组件时，正常是 1 条（+ 兜底条）
- ❌ 同组件拆两条：
修复 ConfigProvider 运行期增删组件键不生效+修复 ConfigProvider 对非本库组件键的处理（读者要把同一个主语读两遍） - ✅
修复 [全局化配置 ConfigProvider](/guide/components/config-provider.html) 组件级主题：运行期增删组件键即时生效（新增覆盖生效、移除覆盖回退 common），theme 中的非本库组件键改为忽略并告警 - 「不相关主题」的判定：读者是否需要做出不同动作 / 关注不同 API 面（如行为修复与破坏性 API 变更并存）——「行为 vs 样式」「代码 vs 文档」这类内部分类不算不相关，不得据此拆条
- ❌ 一条里混入多个不相关主题（如「新增属性 + 构建产物调整」）—— 读者无法判断其中哪句与自己相关
- 同一组件名 / 主题不应在相邻多条里重复出现，出现即说明该合并
- 合并的对象是「同源改动」，不是「为控制条数而压缩」；确实不同源就拆开，宁可条数多也不要堆叠
- 同源文档更新并入该条（不另起「更新文档」条），但仍须按 §3 写明受众与主题
- 收尾条目（如「组件库及文档代码优化」）按维护者习惯保留，不擅自删除或改写 —— 但不是省略文档更新：文档更新须写明「哪类受众文档（使用者文档
docs//README、贡献者文档development//CONTRIBUTING）+ 变了什么主题」；不写具体文件路径，排版 / 格式类调整不展开细节（列数、格式名等）；受众不同的文档更新各自成条，禁止「优化文档」这类一句打包写法
3. 保留必要信息（不得过度概括）
以下必须写清，压缩到看不出影响即不合格：
| 场景 | 要求 |
|---|---|
| 破坏性变更 | 不标注「破坏性变更」字样或用 ⚠️ 等强调标记，按动词正常起句，写明「移除了什么 / 改用什么」 |
| 默认值变化 | 写明旧值 → 新值（未变化时不复述默认值） |
| 需用户改代码 | 写明替代写法 |
| 影响面 / 触发条件 | 写明「什么配置下会踩到」+「同参数下表现是否变化」：interval 改为纯停留时长后，同一取值整体滚动变慢，需调速的读者据此下调；itemStyle 的 maxWidth 仅开启 ellipsis 时失效，不能写成「垂直滚动时失效」 |
| 文档更新 | 按受众写「使用者文档 / 贡献者文档 / README」+ 变了什么主题；不写文件路径与排版细节，不写「优化文档」这类打包表述 |
| 与某修复同源的文档更新 | 并入该修复条（不另起条），仍写明受众 + 主题 |
4. 格式约定
- 每条以动词开头：
新增/优化/增强/修复/重构 - 不使用
⚠️等强调标记：破坏性变更 / 默认值变化 / API 移除同样以动词正常起句，靠正文里的「原 X → 现 Y」说清影响，不加前缀、不加粗警示 - 组件与工具函数名用 Markdown 链接指向文档，如
[文字提示 Tooltip](/guide/components/tooltip.html) - 属性名、API、全局对象等用行内代码包裹
- 条目数不设上限：由改动量自然决定 —— 架构重构、批量破坏性变更的大版本条目自然多，小版本自然少
- 不为凑数拆分（一件事写成多条），也不为控数堆叠或删减信息（多件事挤进一条、砍掉必要语义）
- 每条长度以「一句话可读」为准：合并后的具体结果用括号 / 分句承接，可用分号把「启停 / 节奏 / 样式」等子话题分组
- 「并列项 ≤ 2」只是排版建议（超了先概括或分组），不作拆条依据；是否拆条只按 §2 的主题判定
4.1 条目顺序（2026-10-26 · 不设分类小节）
- 不设
###分类小节（变更 / 新增 / 修复…）：多数版本只有 1–5 条，小节标题比条目本身还重，视觉上与版本号同量级、打断阅读节奏；历史 2.x 版本一直是直排，混排反而更乱。 - 可扫描性靠两件事实现，不靠标题：
- 变更置顶：API 移除 / 更名、默认值变化、需改造的类名与变量，相关条目排在版本块最前（同组件的其余条目可紧随其后）
- 动词起句：
新增/优化/修复/移除/改为一眼可辨类型；⚠️与「破坏性变更」标记一律不写（见 §4）
- 单版本 ≥10 条且跨 3 个以上组件主题时，可用行内粗体
**变更**做视觉分组，仍不用###（避免撑爆页面目录）
4.2 冗余词与模糊表述（2026-10-26 新增）
- 组件链接后不加「组件」二字：
[按钮 Button](/guide/components/button.html)，不写… 组件（历史存量 302 处） - 禁止「优化并更新 X 组件」这类只报动作不报结果的句式（历史存量 249 条，占全部条目 41%）；必须写清改了什么、影响什么
- 不写「完善 / 相关代码 / 部分功能 / 优化调整」等无法定位对象的模糊表述
- 一条内不重复同一个组件链接；相邻条目用「上述 N 个组件」承接已合并的同主题改动
4.3 issue 关联（2026-10-26 新增）
- 有对应 issue 时，条目末补
，关闭 [#编号](https://github.com/themusecatcher/vue-amazing-ui/issues/编号) - 只在确有对应 issue 时写；不写 PR 号、作者、评审信息
5. 版本与历史
- 已发布版本的历史条目默认不回改，用户明确要求时才回改
- 新版本严格按本规范撰写，不因历史风格而妥协
- 回改历史条目只做四件事：删实现细节（见 §6）、去掉
⚠️/「破坏性变更」标记并改为动词起句、按 §2 合并同主题条目、按 §4.1 把 API 变更条目置顶；兜底条目原样保留（见 §6 末条） - 版本块至少 1 条：只写标题、没有条目的空版本块等于「发了个什么都没说的版本」，发布前必须补齐（
3.3.2曾出现空块） - 2026-10-26 已完成一次全量存量回改（170 个版本、616 条 → 564 条）：统一动词（去掉「优化并更新」249 处）、删「… 组件」后缀（300 余处）、修中文标点前空格（232 行）、合并同主题批量条目（如
2.2.12的 22 条主题色改造并为 5 条）、零信息条目统一为「优化 X 的组件实现」、修正 5 处指向错误组件的链接；此后按本规范写新版本，历史不再重复回改 - 回改不改写事实、不合并版本、不动
VersionDateTag、链接与版本号；改完自查「版本数不变、无空版本块」
6. 实现细节一律不写
日志只保留「组件 / 能力 + 可感知结果」，以下内容属于实现细节，出现即删：
| 类别 | ❌ 不写 | ✅ 只写结果 |
|---|---|---|
| 常量数值 | 动效时长由 0.3s 收敛为 0.2s、基线压低 1px、默认色 15% 黑 | 动效时长缩短、基线压低、默认色随模式反转 |
| 缓动 / 曲线 / 关键帧 | 两段同为 ease-out-circ、进场与离场各用一条缓动曲线 | 不写（除非本身就是可配置的 API） |
| 内部 API 与算法 | requestAnimationFrame 合并同帧重算、按 placement 分组管理数据与定时器、模块级统一捕获点击位置 | 只写用户看到的变化 |
| 取值关系 / 派生链 | 内环取外环色的浅一档、按遮罩尺寸取 small 档、底色取主色派生的暗调、文字色改取容器底色 | 内环跟随外环取色、字号随遮罩尺寸变化、底色跟随主题色，不写值从哪来 |
| 内部术语 | 并存两条滚动节拍、与 Swiper 的 interval 口径一致 | 换成使用者视角：越滚越快、stop() 停不下来、不写对标 |
| 构造与结构 | svg 改为声明式渲染、不再在 setup 阶段访问全局对象、改用交互式演示 | 体积减小、修复 SSR 渲染报错、补充可运行示例 |
| 依赖与构建 | 移除 @vuepic/vue-datepicker、新增第三方样式单一数据源、优化 vite 构建配置 | 移除第三方依赖；纯构建 / 脚本 / 测试改动不进日志 |
- 删除优于模糊化：拿不准怎么概括就整句删掉，不要换成「优化了性能 / 调整了逻辑」这类更空的表述
- 例外：常量本身就是公开 API（属性默认值、枚举取值、
CSS变量名）时按 §3 写清旧值 → 新值 - 兜底条目不在回改范围：
组件库及文档代码优化、优化 X 组件代码 / 组件实现、组件库脚本优化等是作者刻意保留的版本记录 —— §2 的「兜底条目不写」只约束新版本，历史条目里已有的原样保留
7. 事实核实
- 日志里出现的组件名 / 属性名 / 事件名 / 文档链接必须在源码或
docs/里核实存在，不靠印象 - 跨组件对标只在两边 API 名真正对得上时才写：❌
与 [轮播图 Swiper] 的 interval 口径一致（Swiper 实为delay/speed）→ ✅ 只写「停留与过渡分开计时」，不写对标 - 默认值、旧值 → 新值回源码确认（
Props接口 /withDefaults/ 组件docs属性表），不凭记忆写数字或属性名 - 修复类条目落笔前先回看 diff，确认「修的范围」与「写的范围」一致（如仅某分支失效，不得写成整体失效）
8. 自检清单
- [ ] 读者决策测试：每条能否改变读者的某个决定？不能则删；括号里的补充是否属于「默认值未变 / 新功能默认行为 / 取值关系」？
- [ ] 是否残留取值关系 / 派生链 / 机制动词（派生、承接、跟随取色、转深、叠压、按…计算）？
- [ ] 每条能否一句话说清「改了什么 + 影响」？
- [ ] 同组件 / 同工具函数族 / 同能力主题的改动是否已优先合并为一条？（先合并，再拆分）
- [ ] 条目数是按「主题数」还是「症状数」定的？同组件的同类修复是否还在分条？（单组件补丁版本通常 1 条）
- [ ] 同一组件名 / 主题是否在相邻多条里重复出现？出现即合并
- [ ] 是否存在「一条堆叠多个不相关主题」的情况？应拆为多条
- [ ] 是否残留症状白描？该留的 API / 属性锚点是否齐全？
- [ ] 破坏性变更、默认值变化是否写明替代用法？未变化的默认值是否已删去复述？
- [ ] 是否写明触发条件与对既有取值的影响（同参数下表现是否变化）？
- [ ] 是否残留
⚠️或「破坏性变更」前缀等强调标记？（一律不写） - [ ] 是否残留根因、算法、内部函数名、内部术语，或需要读者理解内部机制才读懂的表述？
- [ ] 是否残留具体常量数值（时长 / 像素 / 百分比）、缓动曲线、内部 API 或构建手段？（见 §6）
- [ ] 引用的组件 / 属性 / 链接是否核实存在？跨组件对标的两边 API 名对得上吗？
- [ ] 回改历史时是否只删实现细节（兜底条目原样保留）、版本数与版本块结构未受损？
- [ ] 文档更新是否按受众写明「哪类文档 + 变了什么主题」？（不写文件路径与排版细节；同源更新已并入该条；合并 / 拆条沿用项目既有风格）
- [ ] 是否擅自删掉了维护者惯用的收尾条目（如「组件库及文档代码优化」）？应原样保留
- [ ] 是否为了控制条数而删减或模糊了必要信息？（条目数不是压缩目标）
- [ ] API 变更 / 默认值变化条目是否排在版本块最前（§4.1）？是否误用了
###分类小节？ - [ ] 单条是否 ≤120 字（不含链接）？是否残留 ≥3 个分号分句的超载条目？
- [ ] 是否残留「… 组件」后缀与「优化并更新 X 组件」句式？
- [ ] 版本块是否至少 1 条、
date是否非未来日期？ - [ ] 有对应 issue 的是否已补
，关闭 #编号？
9. 反模式清单（2026-10-26 全量盘点）
| 反模式 | 正确做法 |
|---|---|
| 版本块只有标题、没有条目 | 发布前至少 1 条，兜底条不可省 |
| 版本日期写成未来日期 | 预写取当天；发布当天如非同日须更新 |
| 一条塞 5–8 件事（历史最长 670 字） | 按 §1.2 拆分，或按 §2 换成多条同主题条目 |
| 同主题拆多条（4 条都写「暗色下不可见」） | 按 §2 先合并为一条并列式 |
| 同组件跨主题硬塞一条 | 按「读者是否要做不同动作」拆开 |
| 「优化并更新 X 组件」只报动作 | 写清改了什么、影响什么 |
| 组件链接后带「组件」二字 | 删后缀（历史存量 302 处） |
| 文档更新一句打包「优化文档」 | 写明受众（使用者文档 / 贡献者文档 / README）+ 主题 |
| 缺省值复述、常量数值、缓动曲线、内部 API | 按 §6 删除；仅公开 API 的默认值写旧值 → 新值 |
| API 移除 / 默认值变化混在功能条目里排到最后 | 置顶（§4.1） |
用 ### 小节切分只有 1–5 条的版本块 | 直排，靠动词与置顶识别 |
用 ⚠️ /「破坏性变更」前缀强调 | 删标记，动词正常起句 |
发布版本与 package.json version 不一致 | 双处同步后对照校验 |