# @ruan-cat/release-toolkit [![npm version](https://img.shields.io/npm/v/@ruan-cat/release-toolkit?color=yellow)](https://npmjs.com/package/@ruan-cat/release-toolkit) [![npm downloads](https://img.shields.io/npm/dm/@ruan-cat/release-toolkit?color=yellow)](https://npm.chart.dev/@ruan-cat/release-toolkit) 基于 [changelogen](https://github.com/unjs/changelogen) 增强 [changesets](https://github.com/changesets/changesets) 工作流的发布工具包，提供语义化提交解析和 GitHub Release 同步功能。 ## 特性 - 🚀 **完全兼容** - 与现有 changesets 工作流无缝集成，无需重构 - 📝 **语义增强** - 支持 emoji + conventional commits 格式的智能解析 - 🔄 **自动同步** - CHANGELOG.md 与 GitHub Release 内容完全一致 - 🎯 **类型安全** - 完整的 TypeScript 类型支持 - ⚡ **开箱即用** - 预配置了常用的提交类型和 emoji 映射 ## 技术架构 本工具包包含三个核心模块： ```plain @ruan-cat/release-toolkit/ ├── plugins/changelog-with-changelogen # changesets 自定义插件 ├── scripts/sync-github-release # GitHub Release 同步脚本 └── configs/changelogen.config # changelogen 配置 ``` ### 工作流程 ```mermaid 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] ``` ## 安装 ```sh # ✨ Auto-detect npx nypm install -D @ruan-cat/release-toolkit # npm npm install -D @ruan-cat/release-toolkit # yarn yarn add -D @ruan-cat/release-toolkit # pnpm pnpm add -D @ruan-cat/release-toolkit # bun bun install -D @ruan-cat/release-toolkit # deno deno install --dev npm:@ruan-cat/release-toolkit ``` ### 安装对等依赖 本包需要配合 `@changesets/cli` 使用。`typescript` 为可选依赖（用于类型检查）： ```sh # pnpm（推荐）- 安装必需的对等依赖 pnpm add -D @ruan-cat/release-toolkit @changesets/cli # pnpm - 同时安装可选的 typescript pnpm add -D @ruan-cat/release-toolkit @changesets/cli typescript # npm npm install -D @ruan-cat/release-toolkit @changesets/cli # yarn yarn add -D @ruan-cat/release-toolkit @changesets/cli ``` > [!NOTE] > `@changesets/cli` 是必需的对等依赖，用于版本管理和发布工作流。 ## 快速开始 ### 1. 更新 changesets 配置 修改 `.changeset/config.json`： ```json { "$schema": "https://unpkg.com/@changesets/config@3.0.3/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`： ```typescript import config from "@ruan-cat/release-toolkit/configs/changelogen.config"; export default config; ``` ### 3. 更新 GitHub Actions 工作流 在 `.github/workflows/release.yml` 中添加 GitHub Release 同步步骤： ```yaml - 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`： ```typescript #!/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 (推荐) ```plain ✨ feat(auth): 新增OAuth2.0登录功能 🐞 fix(api): 修复用户数据获取错误 📃 docs: 更新API文档和使用示例 🔧 build: 升级依赖包版本 ``` ### 纯 Conventional Commits ```plain feat(auth): 新增OAuth2.0登录功能 fix(api): 修复用户数据获取错误 docs: 更新API文档 build: 升级依赖包版本 ``` ### 仅 Emoji ```plain ✨ 新增用户认证模块 🐞 修复登录页面显示bug 📃 完善README文档说明 ``` ## 生成效果对比 ### 之前 (基础 changesets) ```markdown - 增加发包配置避免部署信息打包。减少体积。 ([`b5b8d38`](https://github.com/...)) ``` ### 之后 (增强版) ```markdown - 🔧 **build**: 增加发包配置避免部署信息打包。减少体积。 ([b5b8d38](https://github.com/...)) - ✨ **feat**(auth): 新增 OAuth2.0 登录支持 ([a1b2c3d](https://github.com/...)) - 📃 **docs**: 更新 API 文档和使用示例 ([e4f5g6h](https://github.com/...)) ``` ## API 文档 ### changelogFunctions changesets 自定义插件函数： ```typescript import { changelogFunctions } from '@ruan-cat/release-toolkit' // 在 .changeset/config.json 中使用 { "changelog": ["@ruan-cat/release-toolkit/plugins/changelog-with-changelogen"] } ``` ### GitHubReleaseSync GitHub Release 同步类： ```typescript 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" }]); ``` ### 配置工具 ```typescript 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`) ### 错误处理 - 提交信息解析失败时回退到基础格式 - 单个包同步失败不影响其他包处理 - 详细的日志输出便于问题排查 ## 开发 ```bash # 开发模式 pnpm dev # 构建 pnpm build # 生成文档 pnpm prebuild ``` ## 许可证 [MIT](./LICENSE) License © 2024 [ruan-cat](https://github.com/ruan-cat) ## 相关项目 - [changesets](https://github.com/changesets/changesets) - 版本管理和发布工具 - [changelogen](https://github.com/unjs/changelogen) - 变更日志生成器 - [@ruan-cat/commitlint-config](../commitlint-config) - 提交信息规范配置 ## 警告 该项目目前完全不能用 原本是期望给 .changeset\config.json 的 changelog 项配置一个日志生成功能，但是现在发现，所依赖的 changelogen 本身是不支持 monorepo 的，不如等待 changelogen 自身支持 monorepo，这样我就不需要封装该包了。 目前该包是用 claude code 自动生成的，效果完全不行，完全不能满足要求的。 暂且放弃，不再继续跟进。