Earthworm 开源贡献指南：从 Fork 到合并，一次完整的 Pull Request 提交流程

Earthworm 开源贡献指南从 Fork 到合并一次完整的 Pull Request 提交流程【免费下载链接】earthwormLearning English through the method of constructing sentences with conjunctions项目地址: https://gitcode.com/GitHub_Trending/ea/earthwormEarthworm 是一个通过连词成句、i1可理解输入等学习理论以游戏化方式帮助用户习得英语的开源项目技术栈为 pnpm monorepo NestJS API Nuxt 前端。本文以官方贡献文档 packages/docs/contribution/index.md 为主线完整讲解从 Fork 仓库到 PR 被维护者合并的六步标准流程并结合仓库内的 commit 规范校验脚本、Changelog 生成脚本与测试体系说明一套可落地的开源协作工作流。读完本文你将能够独立完成一次规范、干净、易于维护者 review 的 Pull Request 提交。开源协作的基本盘Fork → PR 工作流Earthworm 采用 GitHub 主流的Fork Pull Request协作模式外部贡献者不直接往主仓库 push 代码而是先把主仓库 Fork 到自己的账号下在副本上完成开发再通过 Pull Request 把改动提交回主仓库由维护者 review 后合并。整个过程可以拆解为六个步骤Fork 主仓库Clone 自己的 Fork 仓库到本地创建见名知意的功能分支并开发将分支 push 到自己的远程仓库发起 Pull Request 并写好 title 与 description等待维护者 review 与合并。下面逐步展开。一、Fork 仓库得到你自己的副本打开主仓库页面点击右上角的Fork按钮将主仓库复制到自己的账号命名空间下。Fork 出来的仓库会保留主仓库的全部历史记录但拥有独立的提交权限后续的所有 push 操作都发生在这个副本上不会影响主仓库。这一步是先分叉、后回馈的起点你在副本上做的任何实验性改动、失败的分支都不会对主仓库产生任何污染。二、Clone 到本地注意克隆的是自己的仓库Fork 完成后把自己账号下的这个仓库而非原主仓库克隆到本地git clone 你的 Fork 仓库地址这一步的关键点在于注意是自己的仓库如果误克隆了主仓库后续 push 时会因为缺少权限而失败而且无法把功能分支干净地推送回自己的副本。克隆完成后通常还需要把原主仓库添加为一个远程地址upstream用于后续同步主仓库的最新代码例如git remote add upstream 原主仓库地址三、创建功能分支见名知意的 feat/fix 分支在本地新建一个专门用于解决某个问题的分支并在该分支上进行代码功能更新git checkout -b feat/add-feature分支命名有两个硬性要求见名知意分支名称应当能直接表达本次改动的内容与性质例如feat/xxx表示新增功能fix/xxx表示修复缺陷一个分支解决一个问题分支粒度与 PR 粒度保持一致便于维护者针对性地 review 和合并。官方文档特别强调尽量不要在主分支main上做 PR 提交。原因是如果在main上直接开发并提交 PR一旦该 PR 被合并下一次再发起 PR 时之前的 commit 信息会残留其中历史就不干净了。而每次新建一个功能分支PR 合并后直接删除该分支下次再从干净的main上切出新分支即可。因此main分支的主要作用就是同步 Fork 前的主仓库通过 fetch/pull upstream 保持与主仓库一致而不是在上面做开发。另外分支内可以提交多个 commit message官方建议细分功能提交——即把一次大的改动拆成若干个语义独立的小提交而不是把所有改动揉进一个 commit。细粒度提交既方便 review 时按提交逐个理解也方便出问题时回退到任意中间状态。四、推送分支到你的远程仓库开发完成后将功能分支推送到你自己 Fork 的远程仓库git push origin feat/add-featureorigin指向第一步 Fork 出来的你自己的仓库。推送成功后可以在自己的仓库页面上看到这条新分支。五、提交 Pull Request写好 title 与 description推送完成后回到 Fork 的仓库首页页面上会出现提示条点击Compare pull request按钮即可进入 PR 创建页面。进入 PR 页面后需要填写两项关键内容Title标题用一句话概括本次 PR 的核心内容取一个好标题更有利于维护者快速了解改动意图。结合仓库的 commit 规范下文详述推荐沿用type(scope): subject的格式例如feat(api): add comments option、fix(client): handle events on blurDescription描述在 Add a description 中说明这个 PR 解决的问题、改动的思路、影响范围以及如有关联的 issue 编号。描述越清晰维护者 review 的成本越低合并速度越快。确认无误后点击Create pull request提交。此时 PR 会以待 review状态进入主仓库仓库的 CI 与维护者会开始检查你的改动。六、等待仓库维护者合并 PRPR 提交后进入等待期。维护者可能会直接合并approve merge提出修改意见要求你在同一个功能分支上继续提交新 commit 来响应反馈注意不要关闭旧 PR 再开新 PR直接在分支上继续 push 即可PR 会自动更新少数情况下会关闭 PR例如改动方向与项目规划不符或重复。合并成功后你的提交就进入了主仓库的main分支。恭喜你一次完整的 PR 提交成功了 七、工程化保障commit 规范、测试与 ChangelogEarthworm 仓库为这套 PR 工作流配备了完整的工程化约束理解它们能让你的 PR 更顺利地通过 review。Commit Message 规范校验仓库根目录的package.json中声明了prepare: simple-git-hooks安装依赖时即注册 git 钩子而钩子实际执行的校验逻辑在 scripts/verify-commit.ts 中const commitRE /^(revert: )?(feat|fix|docs|dx|style|refactor|perf|test|workflow|build|ci|chore|types|wip|release)(\(.\))?: .{1,50}/; if (!commitRE.test(msg)) { // 打印错误并 process.exit(1) }它读取.git/COMMIT_EDITMSG要求 commit message 严格匹配以下模式类型typefeat、fix、docs、dx、style、refactor、perf、test、workflow、build、ci、chore、types、wip、release之一可选作用域scope括号内标注影响模块如feat(api)、fix(client)描述冒号后 150 个字符支持revert:前缀表示回滚提交。如果 commit message 不符合规范脚本会直接以非零状态退出拒绝该次提交。官方文档特别说明这套方案参考了 Vue 3 的 commit 约定对应 scripts/verify-commit.ts 中的说明。你在第三步规划细分提交时就应当按这个规范来组织每一条 commit message同时 PR 的 title 也建议沿用同一套格式形成分支 → commit → PR三者的风格统一。提交前先跑测试README 中明确要求提交 commit 之前先运行测试测试通过后再提交代码以避免多次提交来解决同一个测试问题。仓库的测试体系分为两部分前端位于apps/clientVitest 单元测试与 Cypress 端到端测试分别用pnpm test:unit:run和pnpm test:e2e:run执行后端位于apps/apiJest 单元测试与端到端测试使用pnpm test:unit与pnpm test:e2e需要依赖 docker-compose 中的 testdb 与 testRedis 服务以及正确的.env.test配置。在根目录执行pnpm test或pnpm test:ci见 package.json即可一键运行前后端全部测试。合并 PR 前CI 也会执行这些测试来兜底。Changelog 自动生成与 release 提交仓库使用conventional-changelog基于规范化的 commit message 自动生成 CHANGELOG.mdpnpm changelog。这意味着你按规范写出的每一条feat/fixcommit都会成为 Changelog 中可读的变更记录。发布流程脚本 scripts/release.ts 中构建完成后会执行release(${packageName}): v${version}这样的提交例如release(client): v1.0.1同样符合 verify-commit 的类型集合。可见从日常功能提交到正式发版整个仓库的 git 历史都遵循同一套可机器解析的规范。八、新贡献者环境准备与更多文档如果你是第一次在本仓库提交 PR需要先把本地开发环境跑起来。仓库根目录的 README.md 提供了完整的如何开始步骤包括pnpm install # 安装依赖 pnpm docker:start # 启动 Postgres / Redis / Logto 等依赖服务 pnpm db:init # 初始化数据库表结构 pnpm db:upload # 首次初始化时上传课程数据 pnpm dev:serve # 启动后端服务 pnpm dev:client # 启动前端服务其中pnpm docker:start通过仓库根目录的 docker-compose.yml 拉起 Postgres 14、Redis 5 与 Logto 1.18.0 等容器pnpm db:init内部会先执行pnpm schema:build再运行earthworm/db包的初始化逻辑见 package.json 的脚本定义。对于需要从零手动配置认证服务 Logto 的贡献者例如不使用仓库提供的初始化数据官方还提供了 packages/docs/contribution/config-logto.md详细讲解清理 Docker Volumes、启动 compose、配置前后端.env文件、在 Logto 控制台创建 API 资源、前端应用与后端 M2M 应用以及创建管理员并分配权限的完整过程。前端与后端环境变量示例分别位于 apps/client/.env.example 与 apps/api/.env.example配置项涵盖LOGTO_APP_ID、LOGTO_CLIENT_ID、LOGTO_CLIENT_SECRET、LOGTO_M2M_API、BACKEND_ENDPOINT、LOGTO_SIGN_IN_REDIRECT_URI等均与源码中 apps/api/src/logto/logto.service.ts 和 apps/api/src/guards/auth.guard.ts 的实际读取逻辑一一对应。文档站点本身也托管在本仓库内基于 VitePress配置见 packages/docs/package.json本地开发文档可运行pnpm docs:dev默认端口 5173。更多入门资料可查阅 packages/docs/get-started/index.md 与 packages/docs/get-started/quick-start.md。小结一次合格的 Earthworm PR背后是一套分支命名规范 → commit 规范校验 → 测试保障 → Changelog 追溯的完整工程链路用feat/xxx、fix/xxx这样的分支隔离改动用type(scope): subject格式的细粒度 commit 记录过程提交前跑通前后端测试最后以一份 title 清晰、描述到位的 Pull Request 交给维护者。掌握这套流程你就能以最低的沟通成本、最干净的历史记录成为 Earthworm 的正式贡献者。【免费下载链接】earthwormLearning English through the method of constructing sentences with conjunctions项目地址: https://gitcode.com/GitHub_Trending/ea/earthworm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考