Lago 开源仓库 Pull Request 提交规范从分支命名到合入评审的完整实操指南【免费下载链接】lagoOpen Source Metering and Usage Based Billing API ⭐️ Consumption tracking, Subscription management, Pricing iterations, Payment orchestration Revenue analytics项目地址: https://gitcode.com/GitHub_Trending/la/lago导读本文以 Lago 开源计量与用量计费项目Open Source Metering and Usage Based Billing API根目录下的 PULL_REQUEST_TEMPLATE.md 为核心完整解读该仓库对贡献者提交 Pull RequestPR的硬性要求与最佳实践。作为 Lago 主仓库的协作入口这份模板规定了从分支创建、提交信息书写、本地测试到 PR 标题、描述、Issue 关联与标签使用的全流程动作。读完本文你将掌握一套可直接照做的 PR 提交清单并理解模板背后与 CONTRIBUTING.md、docs/dev_environment.md 及仓库构建体系docker/Dockerfile相互呼应的工程约束。一、模板定位PR 提交的最后一道自检清单Lago 主仓库是一个典型的 monorepo 型聚合仓库根据根目录 .gitmodulesapiRails API 后端与front前端 UI都是以 Git submodule 方式挂载的子仓库。这意味着 PR 的代码变更往往发生在子仓库中而主仓库的 PR 则负责聚合引用与整体发布。在这种协作模型下PR 的规范化程度直接影响维护者评审效率。PULL_REQUEST_TEMPLATE.md正是一份面向所有贡献者的提交前自检清单。它首先提醒你在提交 PR 之前先确认你的 PR 不是重复的Make sure that your PR is not a duplicate。这一点与 CONTRIBUTING.md 中提交 Bug 报告与功能建议前先执行 cursory search 查找是否已有相同 Issue的规则一脉相承——避免重复劳动是开源协作的第一原则。仓库事实本模板被 CONTRIBUTING.md 明确引用为提交流程的第一步Follow all instructions in the template两者构成完整的贡献者指导体系。二、提交前准备分支、提交信息与单一提交模板要求贡献者在真正创建 PR 之前先满足三个前置条件并给出了具体的命名与格式规范。2.1 在独立分支上开发分支名必须带前缀fix/signin-issue feature/issue-templates模板明确规定分支名必须以fix/或feature/前缀开头且名称必须具有描述性。这一约定带来两个直接收益一眼区分变更类型——fix/代表缺陷修复feature/代表新功能开发为后续 CI 流程与评审阶段提供语义信息便于按分支批量检索变更。分支规范与 CONTRIBUTING.md 中在子仓库目录下git checkout -b your_branch_name新建分支的开发流程配合使用。由于 Lago 的api与front是 submodule实际开发时应在对应子仓库目录内创建分支改动完成后再由主仓库聚合引用。2.2 提交信息短标题 描述性正文模板要求提交信息commit message具有描述性且第一行是简短的标题a descriptive commit message with a short title (first line)。结合 CONTRIBUTING.md 的 Styleguides 章节Lago 对提交信息还有更细的约定使用现在时Add feature 而非 Added feature使用祈使语气Move cursor to... 而非 Moves cursor to...首行不超过 72 个字符首行之后可充分引用相关的 Issue 或 PR 编号纯文档改动时在提交标题中追加[ci skip]跳过 CI 构建整体遵循Conventional Commits约定式提交规范。例如一次符合规范的提交信息feat: add issue templates Add bug report and feature request templates to improve issue triage. closes #1234 [ci skip]2.3 只保留一个提交squash 与 amend模板要求只保留一个提交如果有多个先把它们压缩squash成一个。这保证了主分支上的提交历史线性、可读、便于回滚。若本地测试发现问题需要修改应使用git commit --amend把修正并入现有提交而不是追加新提交# 压缩多个提交为一个交互式变基 git rebase -i HEAD~N # 修改最后一个提交的内容并复用其信息 git commit --amend从仓库的 docker/Dockerfile 可以看到主仓库的最终镜像由front_build前端 pnpm 构建产物与api_buildRails bundle 安装产物两个阶段合并而成——多服务、多依赖的构建链路对历史的可追溯性要求更高单提交约定正是为此服务的。三、本地验证pnpm test必须通过模板的第 2.d 条是最重要的质量门槛pnpm testdoesnt throw any error. If it does, fix them first and amend your commit (git commit --amend).即提交 PR 前必须确保pnpm test无任何报错若有失败先修复并 amend 提交。这条要求与仓库的实际构建方式严格对应前端 UI 基于 Node.js 与 pnpm 构建。docker/Dockerfile 第 11-13 行显示镜像构建阶段通过corepack enable corepack prepare pnpmlatest --activate启用 pnpm然后执行pnpm install pnpm build后端 API 是 Ruby on Rails 应用docs/dev_environment.md 给出了配套的测试与质量命令# 创建测试数据库 lago exec -e LAGO_DISABLE_SCHEMA_DUMPtrue -e RAILS_ENVtest api bundle exec rails db:create db:migrate # 手动运行测试 lago exec api bundle exec rspec lago exec api bundle exec rspec your_file_spec.rb # 运行 linter lago exec api bundle exec rubocop lago exec api bundle exec rubocop -A # 自动修复违规说明lago是docker compose的别名通过lago exec service command可在容器内执行任意命令。前端测试由pnpm test驱动后端测试由 RSpec 驱动二者共同构成 PR 的本地验证闭环。四、创建 Pull Request标题、描述、Issue 关联与标签完成上述准备后才是真正打开 PR 的时机。模板对 PR 本身提出了四点要求。4.1 给 PR 一个描述性的标题PR 标题应当简要概括本次变更的核心内容让维护者无需点开详情即可判断变更方向。4.2 描述你的变更在 PR 描述中说明改了什么、为什么改、怎么验证。建议包含问题背景、变更内容、测试结果。这与 CONTRIBUTING.md 中Bug 报告需描述复现步骤与期望行为的精神一致——信息越充分评审越高效。4.3 使用closes #XXXX自动关闭关联 Issue模板要求如果 PR 修复了某个已存在的 Issue请在描述中写入closes #1234这样 PR 一旦被合并关联的 Issue 会自动关闭避免维护者手动清理 Issue 面板。这一机制要求贡献者先通过 Issue 跟踪问题再以 PR 落地修复形成Issue 讨论 → PR 实现的完整闭环。4.4 添加对应的标签labels模板要求为 PR 添加合适的标签例如feature、improvement、bug等。CONTRIBUTING.md 的 Pull Request Labels 章节列出了评审阶段使用的三组核心标签标签含义needs-review等待维护者或核心团队进行代码评审requires-changes需根据评审意见修改后重新提交评审review-approved已通过评审此外Issue 侧还有enhancement、documentation、bug、question、help-wanted、beginner、duplicate、wontfix、invalid、preview-environment等标签用于帮助贡献者按复杂度筛选首个贡献目标beginner和help-wanted标签下的 Issue 是新手入门的推荐入口。五、提交前必读删除模板并遵守完整贡献规范模板在末尾给出了两条重要提示提交前必须删除模板本身PLEASE REMOVE THIS TEMPLATE BEFORE SUBMITTING——模板是自检清单不是 PR 正文的一部分提交前请阅读完整的 CONTRIBUTING.md贡献指南。CONTRIBUTING.md 对 PR 流程的补充还包括提交后需确认所有 status checks 通过若 CI 失败且你认为与本次变更无关应在 PR 下留言说明原因由维护者重新运行检查评审者还可能要求补充设计、测试或其他修改后才能合入。此外该指南还列出了完整的环境搭建指引见 docs/dev_environment.md与代码风格约束前端统一使用 Prettier 格式化后端遵循 RuboCop 规范。六、完整 PR 提交流程速查表将模板与仓库配套文档整合一份可复制的提交清单如下1. 搜索现有 Issue / PR确认你的贡献不是重复的 2. 在 api 或 front 子仓库创建独立分支git checkout -b fix/xxx 或 feature/xxx 3. 编写描述性提交信息短标题 ≤72 字符遵循 Conventional Commits现在时 祈使语气 4. 将多个提交 squash 为单个提交 5. 本地验证通过 - 前端pnpm test - 后端lago exec api bundle exec rspec - 静态检查lago exec api bundle exec rubocop 6. 打开 PR - 描述性标题 - 说明变更内容 - 关联 Issuecloses #XXXX - 添加标签feature / improvement / bug 等 7. 删除模板占位文字后提交 8. 确认 status checks 全部通过等待评审needs-review → review-approved 或 requires-changes这套流程看似繁琐却是 Lago 这种由api、front、events-processorGo 事件处理管道见 events-processor/main.go等多语言、多服务模块构成的开源项目保持高质量合入的必要保障。遵循它你的贡献就能以最顺畅的方式进入 Lago 主仓库。【免费下载链接】lagoOpen Source Metering and Usage Based Billing API ⭐️ Consumption tracking, Subscription management, Pricing iterations, Payment orchestration Revenue analytics项目地址: https://gitcode.com/GitHub_Trending/la/lago创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考