如何在release-it项目中正确生成和提交CHANGELOG文件

release-it是一个流行的自动化版本发布工具，它能够帮助开发者自动化完成版本发布过程中的多个步骤。其中，生成变更日志(CHANGELOG)是版本发布过程中的一个重要环节。本文将详细介绍如何在release-it项目中正确配置和使用CHANGELOG功能。

CHANGELOG生成的基本原理

release-it通过集成auto-changelog等工具来自动生成项目变更日志。当执行版本发布命令时，工具会扫描git提交历史，按照预定义的模板格式将这些提交信息整理成结构化的变更日志文档。

常见问题分析

许多开发者在初次使用release-it时会遇到CHANGELOG.md文件生成后未被自动提交到版本控制系统的问题。这通常是由于以下原因造成的：

1. 项目目录中不存在CHANGELOG.md文件
2. 文件未被git跟踪
3. 配置中缺少相关提交设置

正确的配置方法

要确保CHANGELOG文件被正确生成并提交，需要遵循以下步骤：

1. 初始化CHANGELOG文件：在项目根目录手动创建一个空的CHANGELOG.md文件，并确保它被添加到git版本控制中。

2. 配置release-it：在.release-it配置文件中设置changelog生成命令和钩子。例如：

import type {Config} from 'release-it'

export default {
  git: {
    requireBranch: 'main',
    changelog: 'bunx auto-changelog --stdout --commit-limit false -u --template ./src/changelog-compact.hbs',
  },
  hooks: {
    'before:init': ['bun run build'],
    'after:bump': ['bunx auto-changelog -p'],
  }
} satisfies Config

3. 理解工作流程：
   • before:init钩子在发布流程开始前执行构建
   • git.changelog配置指定如何生成变更日志预览
   • after:bump钩子在版本号更新后执行完整的变更日志生成

最佳实践建议

1. 模板定制：根据项目需求自定义变更日志模板，保持团队一致的风格。
2. 提交规范：遵循约定式提交(Conventional Commits)规范，使生成的变更日志更具可读性。
3. 版本控制：确保CHANGELOG.md文件始终处于版本控制中，避免每次发布都需手动添加。
4. 多环境测试：在不同环境测试发布流程，确保变更日志生成和提交行为一致。

通过以上配置和实践，开发者可以充分利用release-it的自动化能力，确保每次版本发布都包含准确、完整的变更记录，提高项目维护效率。