React-DnD 贡献指南：环境搭建与 Yarn Deferred Release 版本管理机制-平芜编程栈

React-DnD 贡献指南：环境搭建与 Yarn Deferred Release 版本管理机制

【免费下载链接】react-dndDrag and Drop for React项目地址: https://gitcode.com/gh_mirrors/re/react-dnd

本篇技术指南围绕仓库根目录的 CONTRIBUTING.md 展开，系统讲解如何为 React-DnD 搭建本地开发环境、理解其 Monorepo 结构，并深入剖析本项目采用的 Yarn Deferred Release（延迟发布）工作流——包括 semver impact 文档的编写、yarn version check --interactive的使用方法，以及 CI 中版本检查为何是 Pull Request 失败的最常见原因。读完本文，你将能够独立完成一次 React-DnD 贡献的完整流程：安装环境、开发调试、提交带正确版本影响声明的 PR。

快速开始：贡献者需要的最小环境

官方贡献文档对环境的描述非常精简，只有两样东西：

Node：项目基于 Node.js 运行，所有构建与测试脚本都依赖它。
Yarn：包管理器，可通过npm i -g yarn全局安装。

原文档特别强调了一件事："This project uses Yarn v2, but Yarn v1 will pick up the relevant binaries on this repository."也就是说，虽然项目实际使用的是 Yarn 2（Berry），但贡献者本地即使只有 Yarn 1，也能正常工作。这一机制在仓库中有明确的落点：

根目录 package.json 声明了"packageManager": "yarn@3.3.1"；
.yarnrc.yml 中指定了yarnPath: .yarn/releases/yarn-3.3.1.cjs。

Yarn 1 在检测到yarnPath后会自动委托给仓库内检入的 Yarn 3.3.1 二进制，因此贡献者无需关心本地 Yarn 版本，只需保证 Node 与 Yarn 可执行即可。从仓库的 CI 配置看，当前主流的运行环境是Node 20.x（见 .github/workflows/ci.yml 与 .github/workflows/version-check.yml），而根 package.json 的engines字段声明的最低要求是node >= 10.0，即本仓库的构建脚本覆盖了较宽的 Node 版本区间。

认识仓库：Yarn Workspaces Monorepo 与 Turbo 管道

React-DnD 采用Monorepo结构，根 package.json 通过workspaces: ["packages/*"]将全部子包纳入统一管理。核心发布包包括：

包	定位
`react-dnd`	React 层 API，提供`useDrag`/`useDrop`/`DndProvider`等 hooks 与组件（见 packages/react-dnd/package.json）
`dnd-core`	与 UI 无关的拖拽核心状态机（见 packages/dnd-core/package.json）
`react-dnd-html5-backend`	基于 HTML5 Drag and Drop API 的后端实现（packages/backend-html5）
`react-dnd-touch-backend`	触屏设备后端（packages/backend-touch）
`react-dnd-test-backend`	测试专用后端（packages/backend-test）
`react-dnd-test-utils`	测试辅助工具（packages/test-utils）
`@react-dnd/asap`、`@react-dnd/invariant`、`@react-dnd/shallowequal`	内部工具库（packages/util-asap 等）
`react-dnd-examples`、`docsite`、`eslint-config`、`jest-config`	示例、文档站与工程化配置

跨包的任务编排由Turbo负责，turbo.json 定义了完整的管道：

build依赖上游包构建完成（dependsOn: ["^build"]）；
test依赖build与^build，输出coverage/**/*；
ci聚合build、check、test三步；
release不启用缓存，保证每次发布都是全新执行。

日常开发命令

贡献者在本地执行的最常用命令，都聚合在根 package.json 的 scripts 中：

命令	作用
`yarn install`	安装全部 workspace 依赖（使用仓库内 Yarn 3.3.1）
`yarn build`	经 turbo 逐包构建
`yarn test`	逐包运行 jest 测试并输出覆盖率
`yarn check`	逐包运行 eslint 检查（配合 eslint-config 与 jest-config）
`yarn top_level_checks`	根级质量门禁：拼写检查、Rome 静态检查、模块导入冒烟测试
`yarn ci`	CI 完整流程：先逐包`ci`，再执行`top_level_checks`，最后用`git diff-index HEAD`确认工作区干净
`yarn format`	使用 Rome 统一格式化代码（格式规则见 rome.json：单引号、省略不必要的分号、Tab 缩进）
`yarn release`	发布流程：`run-s clean ci _release_packages`，即清理 → 全量 CI → turbo 逐包`yarn npm publish --tolerate-republish --access public`

其中top_level_checks里包含的_check_modules会执行 module_test/mjs-imports.mjs 与 module_test/cjs-imports.cjs，对发布产物同时做 ESM 与 CJS 两种模块格式的导入验证，确保双格式发布包可用。

核心机制：Yarn Deferred Release 工作流

这是本仓库贡献流程中最需要理解的部分。CONTRIBUTING.md 明确指出：

This project uses Yarn's deferred release workflow. By tracking the Semver impact of each PR we bump versions in a systematic manner.

什么是 Deferred Release

传统的发布方式是"每提交一次就发一个版本"，而deferred release（延迟发布）的核心思路是：每次 PR 不立即发布，而是提交一份记录该改动 Semver 影响的声明文件，由维护者在合适的时机统一批量应用这些版本变更、执行发布。这样版本号的管理与功能开发解耦，发布节奏由维护者掌控。

semver impact 文档是什么

这份"声明文件"就是 Yarn 版本插件生成的semver impact 文档，存放在仓库的 .yarn/versions 目录中。仓库中保留了真实的历史示例，结构非常直观，例如 .yarn/versions/5e1c0f76.yml：

releases: "@react-dnd/asap": patch "@react-dnd/invariant": patch "@react-dnd/shallowequal": patch dnd-core: patch react-dnd: patch react-dnd-examples: patch react-dnd-html5-backend: patch react-dnd-test-backend: patch react-dnd-test-utils: patch react-dnd-touch-backend: patch declined: - react-dnd-documentation - test-suite-cra - test-suite-vite

再如 .yarn/versions/8ec22765.yml：

releases: react-dnd-examples: patch declined: - react-dnd-documentation - test-suite-cra - test-suite-vite

语义清晰：

releases：声明本次改动影响的包及其版本提升级别（patch/minor/major）；
declined：明确声明"这些包本次不发版本"——这比不写更重要，它让版本检查工具知道你已经考虑过它们。

之所以会有declined条目，是因为 .yarnrc.yml 中配置了changesetIgnorePatterns，将测试文件（**/*.spec.{js,ts,tsx}）、文档站（packages/docsite/**）和测试脚手架（packages/test-suite-*/**）排除在版本影响分析之外；而test-suite-cra、test-suite-vite等未配置忽略模式的包在检测到改动时，就会被要求显式声明declined。

如何生成 semver impact 文档

官方贡献文档给出的命令是：

yarn version check --interactive

该命令来自 .yarnrc.yml 中加载的@yarnpkg/plugin-version插件。--interactive会启动交互式提示，逐个询问你的改动对每个受影响包的影响级别（patch / minor / major），或者是否 declined，然后自动生成上述 YAML 文件。它是贡献者提交 PR 前必须执行的一步。

为什么我的 Pull Request 会失败

这是官方 FAQ 中最具实战价值的一条：PR 失败最常见的原因，就是没有编写 semver impact 文档。这与仓库 CI 的版本检查直接相关。

.github/workflows/version-check.yml 展示了对 main 分支的 push 和 PR 都会运行名为 "Version Check" 的 Job，其核心只有一步：

yarn version check

该 Job 会跳过包含release/的 ref（发布分支无需再检查），并通过actions/checkout拉取完整历史（fetch-depth: 0）——这是因为版本检查需要对比当前分支与基线分支的完整提交差异，才能判断哪些包的版本声明是否缺失或不正确。

因此，当你提交 PR 后发现 CI 挂掉，第一反应应该是：运行yarn version check --interactive补充 semver impact 文档，然后重新提交。仓库的 .yarn/versions 目录就是这些文档的累积沉淀，也是维护者批量发布（yarn release→yarn npm publish）的依据。

贡献流程中的其他规范

代码所有权与审查

CODEOWNERS 将全仓库的默认审查人指定为@darthtrevino与@react-dnd/developers团队，任何 PR 都会自动请求他们 review。

Issue 与安全相关文档

提交 bug 或功能需求请使用仓库提供的模板：.github/ISSUE_TEMPLATE/bug_report.md 与 .github/ISSUE_TEMPLATE/feature_request.md；
参与社区讨论前，请先阅读 CODE_OF_CONDUCT.md 中的行为准则；
项目采用 MIT 开源协议，见 LICENSE。

依赖更新自动化

仓库通过 .github/workflows/fix-dependabot.yml 与 scripts/dependabot-autofix.sh 对 Dependabot 提交的依赖更新 PR 做自动修复：当yarn install改动了yarn.lock、.yarn/cache或.pnp.*时，自动提交并推送一个 "Dependabot autofix" 提交，保证锁文件与缓存始终一致。

本地开发环境提示

仓库提供了 .devcontainer/devcontainer.json（基于 Dockerfile 的开发容器配置）以及 .vscode/settings.json（TypeScript SDK、Rome 格式化、文件嵌套等 IDE 设置，推荐插件见 .vscode/extensions.json），可帮助贡献者在编辑器内获得一致的开发体验。