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 2Berry但贡献者本地即使只有 Yarn 1也能正常工作。这一机制在仓库中有明确的落点根目录 package.json 声明了packageManager: yarn3.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-dndReact 层 API提供useDrag/useDrop/DndProvider等 hooks 与组件见 packages/react-dnd/package.jsondnd-core与 UI 无关的拖拽核心状态机见 packages/dnd-core/package.jsonreact-dnd-html5-backend基于 HTML5 Drag and Drop API 的后端实现packages/backend-html5react-dnd-touch-backend触屏设备后端packages/backend-touchreact-dnd-test-backend测试专用后端packages/backend-testreact-dnd-test-utils测试辅助工具packages/test-utilsreact-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.1yarn build经 turbo 逐包构建yarn test逐包运行 jest 测试并输出覆盖率yarn check逐包运行 eslint 检查配合 eslint-config 与 jest-configyarn top_level_checks根级质量门禁拼写检查、Rome 静态检查、模块导入冒烟测试yarn ciCI 完整流程先逐包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 Yarns 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.ymlreleases: 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.ymlreleases: react-dnd-examples: patch declined: - react-dnd-documentation - test-suite-cra - test-suite-vite语义清晰releases声明本次改动影响的包及其版本提升级别patch/minor/majordeclined明确声明这些包本次不发版本——这比不写更重要它让版本检查工具知道你已经考虑过它们。之所以会有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.jsonTypeScript SDK、Rome 格式化、文件嵌套等 IDE 设置推荐插件见 .vscode/extensions.json可帮助贡献者在编辑器内获得一致的开发体验。总结一次标准贡献的检查清单结合官方 FAQ 与仓库工程配置一次符合规范的贡献应当完成安装 Node 与 Yarn本地 Yarn 1 即可仓库会自动切换到 Yarn 3.3.1yarn install安装依赖在packages/*对应子包中修改源码并补充测试各包的__tests__目录与 jest-config 提供了完整的测试基建yarn build、yarn test、yarn check确保构建、测试、lint 全部通过运行yarn version check --interactive编写 semver impact 文档——这是避免 PR 失败的关键一步提交 PR等待 CODEOWNERS 中维护者的 review 与 CI 的 version check 通过。理解了 Deferred Release 机制你就掌握了 React-DnD 社区贡献流程中最核心、也最容易踩坑的一环。更多的项目背景、文档站与示例代码可以继续阅读 README.md、CHANGELOG.md 以及 docsite/markdown/docs 目录下的完整文档。【免费下载链接】react-dndDrag and Drop for React项目地址: https://gitcode.com/gh_mirrors/re/react-dnd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
