@ruan-cat/release-toolkit

基于 changelogen 增强 changesets 工作流的发布工具包，提供语义化提交解析和 GitHub Release 同步功能。

特性

• 🚀 完全兼容 - 与现有 changesets 工作流无缝集成，无需重构
• 📝 语义增强 - 支持 emoji + conventional commits 格式的智能解析
• 🔄 自动同步 - CHANGELOG.md 与 GitHub Release 内容完全一致
• 🎯 类型安全 - 完整的 TypeScript 类型支持
• ⚡ 开箱即用 - 预配置了常用的提交类型和 emoji 映射

技术架构

本工具包包含三个核心模块：

@ruan-cat/release-toolkit/
├── plugins/changelog-with-changelogen    # changesets 自定义插件
├── scripts/sync-github-release           # GitHub Release 同步脚本
└── configs/changelogen.config            # changelogen 配置

工作流程

graph TB
    A[开发者提交 PR] --> B[PR 合并到 main]
    B --> C[GitHub Actions 触发]
    C --> D[changesets/action@v1]
    D --> E[自定义 changelog 插件]
    E --> F[语义提交解析]
    F --> G[生成增强版 CHANGELOG.md]
    G --> H[changesets 发布到 NPM]
    H --> I[GitHub Release 同步脚本]
    I --> J[创建/更新 GitHub Release]

安装

pnpm add -D @ruan-cat/release-toolkit

快速开始

1. 更新 changesets 配置

修改 .changeset/config.json：

{
	"$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
	"changelog": [
		"@ruan-cat/release-toolkit/plugins/changelog-with-changelogen",
		{
			"repo": "your-org/your-repo"
		}
	],
	"commit": false,
	"fixed": [],
	"linked": [],
	"access": "public",
	"baseBranch": "main",
	"updateInternalDependencies": "patch",
	"ignore": []
}

2. 创建 changelogen 配置

在项目根目录创建 .config/changelogen.config.ts：

import config from "@ruan-cat/release-toolkit/configs/changelogen.config";
export default config;

3. 更新 GitHub Actions 工作流

在 .github/workflows/release.yml 中添加 GitHub Release 同步步骤：

- name: 构建并发版
  id: changesets
  uses: changesets/action@v1
  with:
    publish: pnpm release
    version: pnpm run version
    commit: "📢 publish: release package(s)"
    title: "📢 publish: release package(s)"
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

- name: 同步GitHub Release
  if: steps.changesets.outputs.published == 'true'
  run: tsx scripts/sync-github-release.ts
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    PUBLISHED_PACKAGES: ${{ steps.changesets.outputs.publishedPackages }}

4. 创建同步脚本

在项目根目录 scripts/sync-github-release.ts：

#!/usr/bin/env tsx
import { runSync } from "@ruan-cat/release-toolkit/scripts/sync-github-release";

runSync().catch((error) => {
	console.error("Sync failed:", error);
	process.exit(1);
});

支持的提交格式

本工具支持多种提交消息格式：

Emoji + Conventional Commits (推荐)

✨ feat(auth): 新增OAuth2.0登录功能
🐞 fix(api): 修复用户数据获取错误
📃 docs: 更新API文档和使用示例
🔧 build: 升级依赖包版本

纯 Conventional Commits

feat(auth): 新增OAuth2.0登录功能
fix(api): 修复用户数据获取错误
docs: 更新API文档
build: 升级依赖包版本

仅 Emoji

✨ 新增用户认证模块
🐞 修复登录页面显示bug
📃 完善README文档说明

生成效果对比

之前 (基础 changesets)

- 增加发包配置避免部署信息打包。减少体积。 ([`b5b8d38`](https://github.com/...))

之后 (增强版)

- 🔧 **build**: 增加发包配置避免部署信息打包。减少体积。 ([b5b8d38](https://github.com/...))
- ✨ **feat**(auth): 新增 OAuth2.0 登录支持 ([a1b2c3d](https://github.com/...))
- 📃 **docs**: 更新 API 文档和使用示例 ([e4f5g6h](https://github.com/...))

API 文档

changelogFunctions

changesets 自定义插件函数：

import { changelogFunctions } from '@ruan-cat/release-toolkit'

// 在 .changeset/config.json 中使用
{
  "changelog": ["@ruan-cat/release-toolkit/plugins/changelog-with-changelogen"]
}

GitHubReleaseSync

GitHub Release 同步类：

import { GitHubReleaseSync } from "@ruan-cat/release-toolkit";

const sync = new GitHubReleaseSync({
	token: "ghp_xxxx",
	repository: "owner/repo",
});

await sync.syncFromChangesets([{ name: "@my/package", version: "1.0.0" }]);

配置工具

import { extractCommitTypes, createEmojiTypeMap, getSupportedTypes } from "@ruan-cat/release-toolkit";

// 获取所有提交类型
const types = extractCommitTypes();
console.log(types);
// [{ emoji: '✨', type: 'feat', description: '新增功能' }, ...]

// 创建 emoji 映射
const emojiMap = createEmojiTypeMap();
console.log(emojiMap.get("✨"));
// { emoji: '✨', type: 'feat', description: '新增功能' }

集成说明

与 @ruan-cat/commitlint-config 集成

本工具包自动读取 @ruan-cat/commitlint-config 中定义的提交类型和 emoji 映射，确保提交规范与变更日志生成的一致性。

monorepo 支持

针对 monorepo 项目进行了优化：

• 自动识别包结构 (packages/*/CHANGELOG.md)
• 支持 scoped 包名处理
• 独立的 GitHub Release 标签 (@scope/package@version)

错误处理

• 提交信息解析失败时回退到基础格式
• 单个包同步失败不影响其他包处理
• 详细的日志输出便于问题排查

开发

# 开发模式
pnpm dev

# 构建
pnpm build

# 生成文档
pnpm prebuild

许可证

MIT License © 2024 ruan-cat

相关项目

• changesets - 版本管理和发布工具
• changelogen - 变更日志生成器
• @ruan-cat/commitlint-config - 提交信息规范配置

警告 该项目目前完全不能用

原本是期望给 .changeset\config.json 的 changelog 项配置一个日志生成功能，但是现在发现，所依赖的 changelogen 本身是不支持 monorepo 的，不如等待 changelogen 自身支持 monorepo，这样我就不需要封装该包了。

目前该包是用 claude code 自动生成的，效果完全不行，完全不能满足要求的。

暂且放弃，不再继续跟进。