Redwood 贡献者实战指南从本地开发环境搭建到提交 PR 的完整工作流【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood导读本文基于 docs/docs/contributing-walkthrough.md 展开完整拆解 Redwood 框架贡献者从零到提交一个 PR的端到端流程如何区分 Redwood **Project项目**与 **Framework框架**两个代码库、如何用yarn build:test-project搭建功能测试项目、如何用yarn rwfw project:sync把本地框架代码链接到测试项目、如何在框架目录下运行构建/检查/测试命令以及如何在本地与 Gitpod 中完成 PR 提交流程。文中结合当前仓库中真实的脚本源码tasks/framework-tools/、tasks/test-project/、package.json进行逐层印证读完后你将掌握一套可以直接照着操作、且能读懂每一步背后原理的 Redwood 贡献工作流。一、先弄清楚两个代码库Redwood Project 与 Redwood Framework在动手之前必须厘清贡献者语境下的两个核心概念后续所有命令都围绕它们展开。1.1 Redwood Project项目Redwood Project 指你用 Redwood 构建的应用程序代码库——即运行yarn create redwood-app path-to-directory后生成的那套目录典型的api/web/双端结构包含redwood.toml、graphql.config.js、jest.config.js等配置文件可参考仓库内fixtures/test-project/ 或fixtures/example-todo-main/ 等示例项目。文档中强调创建新项目的模板本身也托管在框架仓库中被称为CRWA Template 或 Project Template对应仓库内的 packages/create-redwood-app/templates/ 目录。1.2 Redwood Framework框架Redwood Framework 是包含所有发布到 npm 的redwoodjs/package-name包的 monorepo 代码库也就是当前这个仓库本身。所有包通过 Yarn workspaces 组织见 package.json 中的workspaces配置packages/*、packages/adapters/*/*、packages/auth-providers/*/*等。在 Redwood Project 里框架代码以node_modules/redwoodjs/*的形式存在在框架仓库里它们则是 packages/ 目录下的源码。简单记忆Project 是用 Redwood 做的应用Framework 是Redwood 本身。你贡献的是 Framework但需要用 Project 来验证 Framework 的改动。1.3 贡献文档体系官方贡献文档是分层组织的本仓库中对应关系如下文档定位仓库位置Overview and Orientation贡献总览社区文化、Issue 流程、PR 规范docs/docs/contributing-overview.mdStep-by-step Walkthrough本文从本地环境到提交 PR 的逐步实操docs/docs/contributing-walkthrough.mdReference: Contributing to the Framework Packages框架包贡献参考文档CONTRIBUTING.mdcontributing-overview.md中还指出redwoodjs.com 上的文档面向用 Redwood 开发应用的用户而框架仓库内的贡献文档面向为 Redwood 做贡献的开发者两者职责不同但需要互相链接这正是contributing-walkthrough.md存在的原因。二、开发前的准备工具链与前置知识2.1 推荐开发工具核心团队推荐并实际使用的工具链VS Code官方推荐编辑器框架与项目两个代码库打开时会弹出推荐扩展安装提示GitHub Desktop把 GitHub —— GitHub Desktop —— VS Code 的跨端工作流串联起来从 clone、commit、push 到发起 PR 都能在图形界面完成文档示例全程以它演示但同一流程在命令行下完全等价[Mac] iTerm2 zsh可加 Oh My Zsh比系统自带 Terminal 体验更好建议先保持简单配置避免陷入主题化深坑[Windows] Git for Windows Git Bash或 WSL(2)JS 生态在 Windows 上有不少坑官方优先级是先能开发 Redwood 应用再考虑贡献框架两个推荐方案见 docs/docs/how-to/windows-development-setup.mdGit for Windows 与 Git Bash以及 WSL 社区配置指南Gitpod浏览器端 VS Code 云开发环境会自动初始化一个带测试项目的框架工作区对 Windows 开发者尤其友好详见下文Gitpod章节。2.2 前置知识Git 与 GitHub文档建议在开始贡献前掌握 Git/GitHub 工作流推荐资源包括 GitHub Learning Lab 的《Introduction to GitHub》《First Day on GitHub》《First Week on GitHub》。动手前先完整跑一遍 Redwood 官方教程它同时也是学习 Redwood 及其底层技术栈React、GraphQL、Prisma 等的最佳途径。三、本地开发环境搭建Local Development Setup这是整篇文档的核心实操部分共分为五个步骤Framework 准备 → 测试项目创建 → 框架与项目链接 → 框架包本地测试 → 提交 PR。Step 1准备 Redwood FrameworkFork 框架仓库到个人 GitHub 账号可在 GitHub.com 或 GitHub Desktop 中完成用 GitHub Desktop以 VS Code workspace 打开框架代码在框架根目录执行干净起步命令yarn install # 等价于直接运行 yarn安装 node_modules 依赖 yarn install --force # 简写 yarn -f切换分支后强制重装确保依赖与分支匹配git clean -fxd # 仅在想要从头再来时使用永久删除所有被 .gitignore 忽略的内容node_modules、dist 等 # 警告它会一并删除 Redwood Project 中的 .env 文件可用以下命令保留 git clean -fxd -e .env从main分支创建新分支先git pull同步远端最新代码若是刚 clone 的 fork 则通常已是最新再创建分支。文档推荐的分支命名规范为作者姓名首字母-用连字符连接的描述例如dsp-add-eslint-config-redwood-toml。用 VS Code、GitHub Desktop 或 CLI 的git checkout均可完成。在 package.json 中可以看到yarn install、yarn build、yarn lint等脚本的实际定义例如build实际是nx run-many -t buildbuild:clean是node ./tasks/clean.mjs这些命令正是后续各步骤的基础。Step 2准备 Redwood 测试项目Test Project文档特别强调使用测试项目时的三个关键坑新建项目总是使用npm 上最新稳定版的 Redwood 包它与main分支的框架代码不同步若要用与main分支最新代码对应的包可在项目中执行yarn rw upgrade --tag canary升级到canary 版本用了 canary 不代表在用你的本地框架分支代码——必须运行yarn rwfw project:sync才能链接本地框架且每次切换分支或失步后可能需要从git clean -fxd重新开始。在创建项目的方式上文档给出了四种选项选项 1推荐用构建脚本创建功能测试项目# 在 Framework 根目录执行 yarn build:test-project path/to/directory该命令会用当前框架分支的 Template 代码库安装一个新项目 → 加入教程功能Tutorial features→ 初始化数据库含种子数据。文档评价它90% 的情况下可用也是 Gitpod 默认使用的方案。从当前仓库源码看package.json 中build:test-project对应node ./tasks/test-project/test-project即 tasks/test-project/test-project。该脚本v2会依次执行以下任务见 tasks/test-project/test-project 的globalTasks列表默认从fixtures/test-project/ 复制现成 fixturecopyFromFixture默认true也可选择从零构建调用yarn node ./packages/create-redwood-app/dist/create-redwood-app.js见 tasks/test-project/test-project在项目目录运行yarn install可选--link时执行yarn rwfw project:tarsync链接框架可选--javascript时执行yarn rw ts-to-js转成 JS 项目默认执行yarn rw upgrade -t canary升级到最新 canary与--link互斥见 tasks/test-project/test-project应用 web/api 侧 codemods、生成 dbAuth 密钥写入.env、执行yarn rw prisma migrate reset --force初始化数据库、运行yarn rw lint --fix。另外该脚本还强制要求项目目录不能是框架目录的子目录否则 Yarn 会报错见 tasks/test-project/test-project且只接受一个目录参数例如yarn build:test-project ../test-project。选项 2用本地框架 Template 代码安装全新项目当你的改动涉及 CRWA Template 本身时需要直接使用本地模板创建项目。文档给出的命令是yarn babel-node packages/create-redwood-app/src/create-redwood-app.js path/to/project这等价于yarn create redwood-app …但运行的是本地框架包中的 create-redwood-app 和本地 Template 代码库。注意这正是yarn build:test-project开头所执行的动作。选项 3clone Redwood 教程应用仓库作为 Redwood 教程第二部分起点已更新到最新版本并包含 Blog 功能也常用于本地开发。注意仍需升级到 canary 并留意下一版本的破坏性变更。选项 4安装全新项目yarn create redwood-app path/to/project仅需最新版本模板 无任何功能的全新安装时使用。同样需要注意升级 canary 与破坏性变更问题。TypeScript 提示上述所有创建项目的方式默认生成 JavaScript 项目如需 TypeScript可在运行 create-redwood-app 安装的命令后追加--typescript选项从 tasks/test-project/test-project 的源码看构建脚本本身也是先创建 TS 项目、再用ts-to-js转换。Step 3用 rwfw 把本地 Framework 链接到测试 Project测试项目默认使用 npm 上最新版或 canary的redwoodjs/*包要让项目运行你正在开发的本地框架代码需要在测试项目目录中执行Redwood Frameworkrwfw命令RWFW_PATHframework directory yarn rwfw project:sync示例cd redwood-project RWFW_PATH~/redwood yarn rwfw project:sync其中RWFW_PATH是本地 Redwood Framework 的路径一旦提供给 rwfw它就会记住之后无需再提供除非你移动了框架目录。Windows 开发者注意Windows 可能不接受在命令开头设置环境变量的写法可改用yarn cross-env RWFW_PATH~/redwood yarn rwfw …或先把环境变量写入 shell 再运行命令当前仓库根 package.json 中lint:fw脚本正是用cross-env设置RWJS_CWD的先例。project:sync 启动后控制台会依次打印以下步骤对应源码 tasks/framework-tools/frameworkSyncToProject.mjs 的实际执行顺序clean 并 build 框架先执行yarn build:cleannode ./tasks/clean.mjs再执行yarn buildnx run-many -t build把框架的依赖复制到项目addDependenciesToPackageJson会把框架各包的非redwoodjs依赖合并进项目根package.json见 tasks/framework-tools/lib/project.mjs 与依赖收集逻辑 tasks/framework-tools/lib/framework.mjs——这是你在项目中看到的唯一显式改动根package.json里多出一大堆依赖在项目里运行yarn install把框架包复制到项目copyFrameworkFilesToProject会先删除node_modules/package再按 npm-packlist 的打包文件清单逐个复制见 tasks/framework-tools/lib/project.mjs随后fixProjectBinaries会为各包 bin 创建node_modules/.bin符号链接并写入项目package.json的 scripts见 tasks/framework-tools/lib/project.mjs等待变更用 chokidar 监听packages/目录任一包文件变化后自动重新构建该包并再次复制到项目见 tasks/framework-tools/frameworkSyncToProject.mjs。源码中还有几个值得注意的细节监听会忽略dist、测试文件、README.md、node_modules等路径见 tasks/framework-tools/frameworkSyncToProject.mjs若你修改了某个package.json的dependencies控制台会提示必须重新运行yarn rwfw project:sync同步结束后还会自动把项目被改动的package.json与web/vite.config.js|ts通过 Babel AST 注入optimizeDeps.force: true见 tasks/framework-tools/lib/viteConfig.mjs恢复原状。完成同步后用ctrl c结束链接进程确认项目根package.json中新增的依赖已消失若想重置测试项目运行yarn install --force。Step 4框架包本地测试Build / Lint / Test / Check在框架目录内使用以下命令验证你的代码全部定义于 package.jsonyarn build # 构建所有包nx run-many -t build yarn build:clean # 删除所有旧的构建产物目录 yarn lint # 语法与格式检查并发执行框架与 crwrsca 的 lint yarn lint:fix # 自动修复 lint 错误/警告 yarn test # 运行各包单元测试nx run-many -t test yarn e2e # 运行 Cypress E2E 集成测试node ./tasks/run-e2e yarn check # 检查 Yarn resolutions 与 package.json 格式yarn constraints yarn dedupe --check这些检查全部包含在 GitHub PR 的 CI 自动化中但文档建议本地先跑一遍以理解各自行为。E2E 测试耗时较长不是每次都跑但掌握它很有价值——当 GitHub 上的 CI 失败而需要本地诊断时非常有用。Windows 开发者注意Cypress E2E 在 Windows 上无法工作。两个替代方案使用 Gitpod见下文或在创建 PR 时请求维护者协助。从仓库源码看各包都配有独立的测试配置例如 packages/api/vitest.config.mts、packages/router/vitest.config.mts、packages/cli/vitest.config.mts 等yarn test通过 Nx 并行调度这些测试任务。Step 5提交 PR 文档用 GitHub Desktop 演示了 PR 提交流程但强调同样的流程完全适用于命令行或其他客户端提交文件Commit在本地框架仓库选中当前工作分支勾选左侧列出的修改/新增/删除文件填写简短的 commit message第一框如需更长描述可写在第二框点击 Commit to your-branch-name 完成提交推送文件Push提交后出现本地 commit 计数与 Push origin 按钮点击即可把分支推送到你的 fork 远端也可以继续提交更多 commit 再一次性推送创建 Pull Request推送完成后出现 Create Pull Request 入口浏览器会打开 GitHub 的 Open a pull request 表单填写信息、勾选 Allow edits by maintainers后提交。不使用 GitHub Desktop 时push 完成后访问 github.com 进入你的 fork页面顶部会有发起 PR 的按钮。两个关键建议务必勾选允许维护者更新分支Open a pull request 表单中描述框下方。因为合并前分支总是需要从main更新勾选此选项能显著加速 PR 的推进不要等代码完美了才开 PR大多数沟通和决策都发生在 PR 内。只要代码有一点点改动就建议以Draft PR草稿 PR形式开启用于启动讨论、提问、确认方向。PR 被关闭常因被更新的 PR 取代是流程的一部分。先尝试、再求助比把大量时间花在可能方向错误的代码上要好得多。关于什么是一个好的 PR可参考 docs/docs/contributing-overview.md 中的 What makes for a good Pull Request? 章节好的 PR 应该留下面包屑链接相关 Issue 与论坛讨论、写有帮助的描述代码做什么、解决什么问题、如何用、尽早开 Draft、在 PR 中提问讨论、维护者请求评审几天没回复可以再提醒一次并说明合并后的下一步如有。四、Gitpod浏览器端开发环境Redwood 与 Gitpod 深度集成任何分支或 PR 都能直接初始化一个虚拟工作区。工作区初始化时自动完成检出你的分支或 PR 代码运行 Yarn 安装通过yarn build:test-project创建功能测试项目将框架代码与测试项目同步即project:sync所做的事启动测试项目的 dev server。浏览器提示Brave 与 Safari 在 Gitpod 上存在已知 bug建议使用 ChromeEdge 和 Firefox 也值得一试。两种启动 Gitpod 工作区的方式方式一从 PR 启动。每个 PR 都会用 PR 分支触发一次 Gitpod 预构建在 PR 底部的 checks 列表中找到 Gitpod点击 Details 链接即可进入方式二使用 URL 模式。初始化工作区的 URL 模板为https://gitpod.io/#URL for branch or project例如用 Redwood 框架main分支启动https://gitpod.io/#https://github.com/redwoodjs/redwood用 PR #3434 启动https://gitpod.io/#https://github.com/redwoodjs/redwood/pull/3434需要再次强调的是不要因为用 Gitpod 就跳过本地环境搭建章节——Gitpod 内部使用的是同一套工作流与工具来完成初始化理解它如何工作才能用好它。五、结合仓库源码的深度印证核心命令背后的实现为了让上文中的每一步都可验证这里把核心命令与仓库中的真实实现一一对应文档中的命令/概念仓库中的实际实现关键行为yarn build:test-project pathpackage.json → tasks/test-project/test-project复制 fixture 或从 create-redwood-app 构建 →yarn install→ canary 升级 → codemods → dbAuth 密钥 →prisma migrate reset→ lint --fixRWFW_PATH… yarn rwfw project:syncpackage.json → tasks/framework-tools/frameworkSyncToProject.mjscleanbuild 框架 → 注入框架依赖 →yarn install→ 复制包文件/修复 bin → chokidar 监听变更并增量重建yarn rwfw project:tarsyncpackage.json → tasks/framework-tools/tarsync/bin.mtsbuild:test-project --link时用于把框架以 tarball 方式同步进项目框架依赖注入tasks/framework-tools/lib/framework.mjs、tasks/framework-tools/lib/project.mjs遍历所有redwoodjs包收集非红木依赖跳过storybook-framework-redwoodjs-vite合并进项目根package.json重复依赖版本不一致会直接抛错包文件复制tasks/framework-tools/lib/project.mjs用npm-packlist计算每个包的发布文件清单先rimraf清空node_modules/package再逐文件复制Vite 配置临时修改tasks/framework-tools/lib/viteConfig.mjs用 Babel 解析web/vite.config.js|ts并注入optimizeDeps: { force: true }退出时自动还原yarn checkpackage.jsonyarn constraintsyarn dedupe --check检查 Yarn resolutions 与依赖去重这些印证表明文档描述的clean → build → 注入依赖 → install → 复制 → 等待变更五步流程与 tasks/framework-tools/frameworkSyncToProject.mjs 中的实际执行顺序完全一致该脚本中五步依次对应yarn build:clean、yarn build、addDependenciesToPackageJson、yarn install、copyFrameworkFilesToProjectfixProjectBinaries并且脚本在收到 SIGINT/进程退出时会自动把项目package.json与 vite 配置恢复原状见 tasks/framework-tools/frameworkSyncToProject.mjs——这与文档中用 ctrl c 结束链接进程后确认 package.json 不再有多余依赖的操作指引互为印证。六、常见问题速查Q1新创建的测试项目为什么用不上我main分支的新代码因为新建项目默认使用 npm 最新稳定版包。先yarn rw upgrade --tag canary升级到 canary再yarn rwfw project:sync链接本地框架代码两者缺一不可。Q2project:sync改了我的项目文件怎么还原进程退出含ctrl c时会自动还原根package.json与web/vite.config.js|ts。脚本给出的手动恢复步骤是撤销对yarn.lock的改动 → 删除项目node_modules→ 重新yarn install。Q3切换分支后测试项目状态混乱怎么办文档建议从git clean -fxd必要时加-e .env保留环境变量开始重新走yarn install→project:sync的完整流程。Q4Windows 上无法运行 E2E 或 rwfw 命令E2ECypress在 Windows 上不支持用 Gitpod 或请维护者协助RWFW_PATH环境变量前缀写法被拒时改用cross-env前置或先写入 shell 环境变量。Q5代码改到一半适合开 PR 吗适合。用 Draft PR 尽早开启讨论与确认方向避免在错误方向上投入大量时间PR 被关闭或被取代都是协作流程的正常部分。结语从 Fork 框架、搭建功能测试项目、rwfw project:sync链接本地代码到跑通 build/lint/test/check 四件套再到提交 PR 与善用 Draft PR整套贡献工作流的每一步都能在仓库源码中找到对应的真实实现tasks/test-project/、tasks/framework-tools/、package.json。对本仓库有更深入兴趣的读者还可以继续阅读 CONTRIBUTING.md 获取框架包贡献的参考细节或浏览 docs/docs/contributing-overview.md 了解社区协作规范与 PR 评审标准。现在Fork 一份代码、开一个分支去提交你的第一个 PR 吧。【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考