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 Request（PR）的硬性要求与最佳实践。作为 Lago 主仓库的协作入口，这份模板规定了从分支创建、提交信息书写、本地测试到 PR 标题、描述、Issue 关联与标签使用的全流程动作。读完本文，你将掌握一套可直接照做的 PR 提交清单，并理解模板背后与 CONTRIBUTING.md、docs/dev_environment.md 及仓库构建体系（docker/Dockerfile）相互呼应的工程约束。
一、模板定位：PR 提交的"最后一道自检清单"
Lago 主仓库是一个典型的 monorepo 型聚合仓库：根据根目录 .gitmodules，api（Rails 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_build（Rails bundle 安装产物）两个阶段合并而成——多服务、多依赖的构建链路对历史的可追溯性要求更高，单提交约定正是为此服务的。
三、本地验证：pnpm test必须通过
模板的第 2.d 条是最重要的质量门槛：
pnpm testdoesn't 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 pnpm@latest --activate启用 pnpm，然后执行pnpm install && pnpm build； - 后端 API 是 Ruby on Rails 应用，docs/dev_environment.md 给出了配套的测试与质量命令：
# 创建测试数据库 lago exec -e LAGO_DISABLE_SCHEMA_DUMP=true -e RAILS_ENV=test 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： - 描述性标题 - 说明变更内容 - 关联 Issue：closes #XXXX - 添加标签：feature / improvement / bug 等 7. 删除模板占位文字后提交 8. 确认 status checks 全部通过，等待评审（needs-review → review-approved 或 requires-changes）这套流程看似繁琐，却是 Lago 这种由api、front、events-processor（Go 事件处理管道，见 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），仅供参考
