nuqs 仓库发布与 Git 工作流：Conventional Commits、语义化版本与自动化发布实战

前端状态管理【免费下载链接】next-usequerystateType-safe search params state manager for React frameworks - Like useState, but stored in the URL query string.项目地址https://gitcode.com/gh_mirrors/ne/next-usequerystate点击查看免费下载本指南基于仓库内 .agents/docs/git-workflow.md 整理完整讲解 nuqsType-safe URL query string ↔ React state 同步库monorepo 的版本管理、提交规范、Pull Request 标准与自动化发布流程。读完本文你将掌握如何写出被发布流水线正确识别的 Conventional Commits、语义化版本号如何被自动计算、PR 标题与版本提升之间的一致性校验机制以及维护者在架构决策、文档同步上的配套规范。Conventional Commits 提交规范nuqs 仓库要求所有提交遵循 Conventional Commits 规范并由 review 强制把关。该规范不是可有可无的格式偏好——它直接决定了版本号如何被自动计算见下文「语义化版本与自动发布」因此每次提交的信息都会进入发布决策链。提交信息格式type(scope): subject body footer其中scope可选subject是必填的简短描述body与footer用于补充动机和破坏性变更说明。仓库对提交解析的实现位于 packages/scripts/lib/conventional-commits.ts其中parseSubject使用正则^([a-z])(?:\([^)]\))?(!)?: (.)$解析提交主题第一行把type、!标记与描述拆开parseCommit则在parseSubject基础上额外从正文中识别BREAKING CHANGE:/BREAKING-CHANGE:footer严格大小写正文中的小写提及会被忽略。这意味着破坏性变更既可以用主题中的!标记也可以在正文 footer 中声明两者都会被检测到。提交类型文档规定的核心提交类型如下feat:— 新功能fix:— Bug 修复perf:— 性能改进docs:— 仅文档变更refactor:— 代码重构无功能变化test:— 新增或更新测试chore:— 工具链、依赖、配置仓库在 package.json 中通过 commitlint 实际强制了type-enum规则允许的类型枚举为build、chore、ci、clean、doc、feat、fix、perf、ref、revert、style、test并开启body-leading-blank正文前必须空行。可以看到仓库实际使用的枚举在docs/refactor等类型上采用了doc/ref等缩写形式且额外支持ci、build、revert、style、clean等类型——提交时应以 commitlint 配置为准。破坏性变更破坏性变更需要两步标记使用feat!:或fix!:前缀在类型后加!在 footer 中添加BREAKING CHANGE: description。示例feat!: change parser return type BREAKING CHANGE: parseAsInteger now throws on invalid input instead of returning null从源码看bumpForType将破坏性变更一律映射为major提升见 packages/scripts/lib/conventional-commits.ts因此在解析逻辑中哪怕只通过正文 footer 标记破坏性变更主题无!也足以强制触发一个主版本号提升——这是parseCommit单独处理 body footer 的原因。语义化版本与自动发布版本号提升由semantic-release自动化完成规则如下Patchv1.2.3 → v1.2.4—fix:提交Minorv1.2.0 → v1.3.0—feat:提交Majorv1.0.0 → v2.0.0—feat!:或fix!:破坏性变更不要手动提升版本号——自动化会处理这一切。任何手动version改动都可能与发布流水线产生冲突。源码中的版本计算实现仓库在packages/scripts下实现了一套独立于semantic-release工具链的发布编排脚本其中 packages/scripts/compute-version.ts 是版本计算核心。它读取 git 提交历史packages/scripts/lib/git.ts 中的readReleaseHistory通过git log输出提交图与v*标签装饰对上一次 GA 发布以来的提交逐一调用bumpForType取最高级别的 bump 作为本次提升幅度提交类型提升级别对应版本号变化feat!:/fix!:破坏性majorv1.0.0 → v2.0.0feat:minorv1.2.0 → v1.3.0fix:/perf:/revert:patchv1.2.3 → v1.2.4其他chore、docs、test等无提升不触发发布若自上次发布以来没有版本提升类提交脚本输出needsReleasingfalse并干净退出流水线随即停止而不是报红。stable 与 beta 双通道发布仓库的发布流水线区分两个通道见 packages/scripts/lib/version.ts 中的Channel类型与 packages/scripts/compute-version.tsstable 通道发布到 npm 的latestdist-tag版本号形如vX.Y.Zbeta 通道发布到betadist-tag版本号形如vX.Y.Z-beta.N其中N取该目标 GA 版本下已存在 beta 序号的最大值加一highestBetaNumber按最大值而非计数计算即使早期 beta 被删除也不会序号冲突。标签版本语义在 packages/scripts/lib/version.ts 中有严格定义GA 标签是没有任何预发布段的合法 semverbeta 标签必须严格是beta.数字形态-rc、-alpha或其他预发布段都不属于本仓库发布通道。Release 分支发布分支next推送到next的提交触发版本计算与发布NPM 发布自动完成版本历史可直接查看仓库的v*git 标签packages/scripts/lib/git.ts 中readAllTags即通过git tag --list v* --merged origin/next读取合并到next分支的版本标签。发布后packages/scripts/release-finalize.ts 会自动对受影响的 PR、Issue、Discussion 回帖通知「已发布在 nuqs 」并在帖内附带pnpm add nuqsversion安装命令通知通过 HTML 注释标记实现幂等重复运行不会重复通知。Pull Request 标准提交 PR 前确保提交信息符合 Conventional Commits本地运行测试pnpm test验证类型级测试type-level tests如有必要更新文档考虑破坏性变更是否需要说明迁移路径。根目录 package.json 中定义了 monorepo 的统一脚本pnpm test通过 turbo 流式运行各包测试AGENTS.md 建议聚焦测试时使用根 Turbo 命令例如pnpm run test --filter nuqs或pnpm run test --filter e2e-next并提醒完整测试套件约需 5–10 分钟包含构建 单元 类型 e2e。PR 描述PR 描述需包含Summary— 这个 PR 做什么、为什么做Type— 是 feature、fix、refactor 还是文档更新Changes— 修改区域的高层清单Testing— 新增了哪些测试覆盖Breaking Changes— 如有描述迁移路径。PR 标题PR 标题应与第一条提交信息保持一致Conventional Commits 格式feat: add new parser typefix: handle edge case in batchingdocs: update adapter setup guide仓库通过 packages/scripts/validate-pr-title.ts 在 CI 中强制这一规则标题必须匹配type(scope)?(!)?: description格式type必须位于 commitlint 的type-enum白名单内且长度不超过 100 字符HEADER_MAX_LENGTH。更关键的是版本提升一致性检查如果 PR 标题使用了会触发版本提升的类型feat→ minor、fix/perf→ patch、revert→ 视被回滚提交而定则该 PR 必须包含核心包packages/nuqs/下的变更CORE_PACKAGE_PREFIX packages/nuqs/否则 CI 会拒绝——因为一个不包含库代码变更的 PR 不应触发任何版本发布。属于非提升类型的标题doc、chore、test、ci、build、style、ref、clean则跳过此项检查。PR 检查清单标记 ready for review 之前pnpm test本地通过为新行为新增/更新测试所有新导出均已写入文档如有必要更新文档内容面向用户的行为变更已更新 README无意外 bundle 体积增长Conventional Commit 提交信息无未解决的 TODO无多余的 console.log受控的 debug 日志除外文档更新何时更新文档以下场景必须同步更新文档公开 API 表面变化新增导出、hook 签名变更Parser 行为变化解析规则、序列化规则变更Adapter 需求变化新增选项、破坏性变更。更新哪些内容README.mdExamples 部分API referenceAdapter 列表MDX 文档packages/docs/content下镜像 README 相关章节补充详细示例记录配置选项文档应用的源码与内容位于packages/docsNext.js FumadocsMDX 内容在 packages/docs/content 下AGENTS.md 中亦有「更新文档」任务的入口指引指向本文档的 Documentation 章节。文档最佳实践保持示例简洁优先链接已有 demo 而非复制代码与现有文档风格保持一致示例要覆盖常见使用场景新增章节时更新目录table of contents。决策日志进行非平凡的架构变更时在 AGENTS.md 的 Decision Log 部分添加简短记录格式YYYY-MM-DD - Title - Rationale / Impact / Migration (if any)。示例2025-01-15 - Add batching optimization - Reduces URL updates by 40% when multiple state changes occur in same tick. No migration needed. 2025-01-20 - Parser requires eq method - Enables custom equality checks for complex types. Existing parsers automatically compatible.决策日志位于仓库根目录 AGENTS.md其开发指南段落集中引用了 .agents/docs/adapter-development.md、.agents/docs/parser-implementation.md、.agents/docs/api-design.md、.agents/docs/testing.md 等配套文档。发布说明的自动化生成则位于 packages/scripts/release-notes-automation.ts它会按「Breaking changes / 分类变更 / Thanks」结构组装 markdown将 PR 标题中的反引号代码片段转换为code标签并通过 GitHub Actions 的 heredoc 输出nameDELIM安全地回传多行内容供发布草稿使用。自动化与工具团队使用的自动化Conventional Commits由 commit linting 强制执行类型检查属于pnpm test的一部分版本与发布next分支自动计算版本、打标签并发布到 npmstable/beta 双通道PR 检查lint、测试、类型检查在 CI 中自动运行另有 PR 标题 lint 与版本提升一致性校验packages/scripts/validate-pr-title.ts。Agent 行为边界Agents 可以生成 parser 样板代码更新文档中的 Adapters 章节追加 PR 检查清单结果在提出变更前本地运行测试与 lint。Agents 不得自动提交版本提升由发布自动化处理强制推送 main/master修改 git 配置跳过 git hooks。这些边界同时记录在 AGENTS.md 的「Exit Conditions for Agent Tasks」中任务完成的标志是检查清单全部满足、pnpm test本地通过、文档与行为一致、无未解决 TODO、无多余的 console 日志。小结nuqs 的发布流程是一套以 Conventional Commits 为唯一入口、以next分支为发布源头、由自动化完成「版本计算 → 打标签 → 发布 npmlatest/beta 双通道→ 回帖通知」的闭环体系。对贡献者而言最有价值的实践是提交信息与 PR 标题始终遵循规范格式破坏性变更记得加!与BREAKING CHANGEfooter版本提升类 PR 务必包含packages/nuqs/下的核心变更——满足这些约束其余环节都会由流水线自动接管。赞分享前端状态管理【免费下载链接】next-usequerystateType-safe search params state manager for React frameworks - Like useState, but stored in the URL query string.项目地址https://gitcode.com/gh_mirrors/ne/next-usequerystate点击查看免费下载相关推荐Marked 版本发布指南semantic-release、Conventional Commits 与语义化版本管理实战Marked 版本发布指南semantic release、Conventional Commits 与语义化版本管理实战 Marked 作为一款以速度为设计前端browserless 发布自动化全流程指南release-please 与 Conventional Commits 驱动的 npm 与 Docker 协同发布browserless 发布自动化全流程指南release please 与 Conventional Commits 驱动的 npm 与 Docker 协同后端API网关Crossplane 发布流程与发布工程月度发布节奏、语义化版本与自动化流水线设计Crossplane 发布流程与发布工程月度发布节奏、语义化版本与自动化流水线设计 本篇技术指南以 Crossplane 项目早期沉淀的发布流程设计文档 d云原生后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考