changelog-check-guide.md 6.88 KB

Raw Blame History Permalink



CHANGELOG 检查机制


本文档说明如何定期检查 CHANGELOG 是否有漏记，确保项目变更记录的完整性。


🎯 检查机制的重要性


为什么需要定期检查？


防止遗漏：忙碌的开发中容易忘记更新 CHANGELOG

保持同步：git 提交和 CHANGELOG 记录保持一致

项目追溯：完整的历史记录便于问题排查和功能回顾

团队协作：新成员通过 CHANGELOG 快速了解项目演进


🛠️ 自动化检查工具


快速开始

# 检查最近 7 天（默认）
pnpm run changelog:check

# 检查最近 30 天
pnpm run changelog:check:30

# 检查所有提交
pnpm run changelog:check:all


输出示例

======================================
  CHANGELOG 漏记检查工具
======================================

检查范围: 最近 7 天

[1/4] 正在获取 git 提交记录...
  找到 25 个提交

[2/4] 正在解析 CHANGELOG 记录...
  找到 18 条记录

[3/4] 正在对比分析...

📊 每日提交统计:
     5 2026-02-01
     12 2026-01-31
     8 2026-01-30

🔍 可能漏记的日期:
  ✗ 2026-01-30 - 8 个提交未记录

[4/4] 生成详细报告...

======================================
  检查完成
======================================

✓ 详细报告已保存到: docs/changelog-check-report-20260201.md


📅 检查频率建议


每周检查（推荐）⭐

时间: 每周五下午或周一早上

目的:


检查上周的变更是否都已记录
在周会前准备好项目进展总结


命令:

pnpm run changelog:check


流程:

1. 运行检查脚本
2. 查看生成的报告
3. 如果有漏记，补充到 CHANGELOG.md
4. 提交更新


每月检查（必需）

时间: 每月最后一天或第一天

目的:


全面检查当月所有变更
确保月度报告的准确性
为项目回顾做准备


命令:

pnpm run changelog:check:30


发布前检查（必需）

时间: 每次版本发布前

目的:


确保版本 CHANGELOG 完整
避免发布后才发现漏记


命令:

pnpm run changelog:check:all


🔄 定期检查流程


开发者个人流程


每次完成任务后

# 1. 完成功能开发
git add .
git commit -m "feat: 新增xxx功能"

# 2. 立即更新 CHANGELOG
# 编辑 docs/CHANGELOG.md
# 添加本次变更记录

# 3. 再次提交 CHANGELOG
git add docs/CHANGELOG.md
git commit -m "docs: 更新 CHANGELOG"

# 4. 推送
git push


每周五下午

# 1. 运行检查脚本
pnpm run changelog:check

# 2. 如果有漏记，补充 CHANGELOG
vim docs/CHANGELOG.md

# 3. 提交更新
git add docs/CHANGELOG.md
git commit -m "docs: 补充本周变更记录"
git push


团队协作流程


每次 PR/MR 时

检查清单:


 CHANGELOG 已更新

 所有重要变更都已记录

 格式符合标准模板


CI 集成（可选）:

可以在 CI 流程中自动运行检查：

# .gitlab-ci.yml (示例)
changelog-check:
  stage: test
  script:
    - bash scripts/check-changelog.sh 7
  allow_failure: true
  only:
    - develop


📋 漏记补充流程


发现漏记后


1. 查看详细报告

# 打开生成的报告文件
cat docs/changelog-check-report-20260201.md


报告会列出所有未记录的提交：

### 未记录的提交详情

**2026-01-30** (8 个提交):
- refactor(SearchBar): 替换 NutUI Input 为原生 input 元素
- fix: 修复搜索组件样式和搜索逻辑问题
- feat(components): 添加可复用的 SearchBar 组件
...


2. 补充到 CHANGELOG.md

按照标准格式补充记录：

## [2026-01-30] - 搜索功能重构与优化

### 新增
- 新增 SearchBar 组件并替换多个页面中的搜索框

### 重构
- 重构 SearchBar 组件
  - 替换 NutUI Input 为原生 input 元素

### 修复
- 修复搜索组件样式和搜索逻辑问题

---

**详细信息**：
- **影响文件**: src/components/SearchBar.vue, src/pages/search/index.vue
- **技术栈**: Vue 3, Taro
- **测试状态**: ✅ 已通过


3. 提交补充

git add docs/CHANGELOG.md
git commit -m "docs: 补充 CHANGELOG 漏记的 N 条变更记录"
git push


⚙️ 自动化检查脚本说明


脚本位置

scripts/check-changelog.sh


使用方式

# 直接运行
./scripts/check-changelog.sh [days]

# 通过 npm 运行
pnpm run changelog:check        # 最近 7 天
pnpm run changelog:check:30    # 最近 30 天
pnpm run changelog:check:all   # 所有提交


脚本功能


获取 git 提交记录


扫描指定天数内的所有提交
提取提交哈希、日期、描述


解析 CHANGELOG


提取所有已记录的日期
统计记录数量


对比分析


每个日期的提交数量 vs CHANGELOG 记录
识别漏记的日期


生成报告


保存为 docs/changelog-check-report-YYYYMMDD.md

列出所有未记录的提交详情


🎯 检查时机总结


检查类型
频率
范围
用途


快速检查
每周
7 天
周会准备


月度检查
每月
30 天
月度总结


发布检查
发布前
所有
版本发布


专项检查
随时
自定义
特殊需求


💡 最佳实践


1. 及时记录

原则: 完成功能后立即记录

# ❌ 不好：积累很多提交后一次性记录
git commit -m "feat: 功能A"
git commit -m "feat: 功能B"
git commit -m "fix: 修复C"
# ... 一周后才更新 CHANGELOG

# ✅ 好：每个功能完成后立即记录
git commit -m "feat: 功能A"
vim CHANGELOG.md  # 立即记录
git commit -m "docs: 更新 CHANGELOG"


2. 定期检查

建议: 设置日历提醒


每周五 17:00: 提醒检查本周变更

每月最后一天: 提醒检查当月变更

发布前一天: 提醒检查所有变更


3. 团队协作

Pull Request 模板:

## CHANGELOG 检查
- [ ] CHANGELOG 已更新
- [ ] 所有重要变更都已记录
- [ ] 格式符合标准模板

## 检查命令
```bash
pnpm run changelog:check:7


🔧 故障排查


问题：脚本没有执行权限

解决:

chmod +x scripts/check-changelog.sh


问题：报告显示没有提交

原因: 指定天数内没有 git 提交

解决: 增加检查天数

pnpm run changelog:check:30


问题：CHANGELOG 路径错误

解决: 检查是否在项目根目录

pwd  # 应该显示项目根目录
ls docs/CHANGELOG.md  # 确认文件存在


📚 相关文档


CHANGELOG 自动记录规则
CHANGELOG 文档
技术决策记录


最后更新: 2026-02-01
维护者: Claude Code
项目: Manulife WeApp