Bagisto 贡献指南：从认领 Issue 到 PR 过审的 7 道硬关卡

Bagisto 贡献指南：从认领 Issue 到 PR 过审的 7 道硬关卡

【免费下载链接】bagistoOpen Source eCommerce & Multi-Vendor Marketplace Platform Built with Laravel for Enterprise-Scale Commerce, Supporting 10M+ SKUs项目地址: https://gitcode.com/gh_mirrors/ba/bagisto

你给 Bagisto 提的第一个 PR，多半死在 Pint 那一步。这篇贡献指南写给第一次提 PR 的开发者：从认领 Issue、选分支，到代码规范与 PR 前检查清单，七道关卡一次讲清。

开工前：先过认领、分支、共识三道闸门

闸门 1：认领 Issue，先留言后写码。

你必须先在 Issue 下留言并等待被指派，再动手写任何代码。一句简短的 "I'd like to take this" 就够。认领前先检查是否已有 assignee 或已在评论区表示在处理；如果认领后长时间没有动静，在原帖里询问进展，不要开一个竞争性的 PR。背后的逻辑是，同一个 Issue 常被多人同时认领，重复劳动往往到第二份 PR 到达时才被发现，白白浪费别人一个晚上。

闸门 2：按变更类型选分支，同一条分支切出、同一分支提交。

当前活跃的是三条线：2.4与2.5是当前发布线，master是下一条发布线（当前对应 2.6）；1.x、2.1、2.2、2.3不再接收任何新工作。分支策略就是下面这张表：

变更类型目标分支
Bug 修复受影响的发布线，通常是2.5
向后兼容的小改进同一条发布线
主要新特性或破坏性变更master

你必须从目标分支拉出工作分支，并向同一条分支开 PR，不要跨分支混提，仓库里也没有development分支。每个修复单独一个分支，按 Issue 命名，例如issue-1234；提交主题用 Conventional Commits：bug 修复写fix: <what changed>，新功能写feat: <what it adds>。背后的逻辑是发布线就是各版本的发布列车，跨分支的 PR 维护者没法直接合入对应版本。

闸门 3：方案先对齐，用最小实现展示形态。

提功能必须在动手实现之前就在 Issue 里达成方案共识。背后的逻辑是，一个"惊喜式"到达的 PR 更可能因为方向被拒，而不是因为代码被拒。同时不要只抛空泛想法，至少实现足够展示解决方案形态（shape of the solution）的部分。Bug 类先搜 Issue，确认它是普遍问题而不是你本地配置的问题，再给报告配上标题、清晰描述、你所在的版本号和足够的复现细节；一个 bug 报告本身也可以表现为包含失败测试用例的 PR。

动手时：机器能查的，与评审者逐条看的

机器能查的：Pint 与 PHPDoc 格式

代码风格由 Laravel Pint 裁定，配置文件pint.json只有一行{"preset": "laravel"}。开 PR 前必须运行它，因为 CI 执行的是同一项检查：

vendor/bin/pint # 自动修复，改写文件 vendor/bin/pint --test # 只检查；CI 实际运行的就是这种形式

Pint 不会格式化.blade.php文件，Blade 模板的风格靠手工。背后的逻辑是 CI 只看--test的退出码，风格有问题会在人工评审开始前就被拒。另外，你触碰的文件里已有的风格违规也算你的，扫描整个类而不是只看改动的行。

PHPDoc 的格式同样有硬性约定：@param在类型两侧各留两个空格，例如@param string|array $loader。核心原则是类型信息属于函数签名，凡语言本身能表达的类型都写进签名，@param与@return只补充原生类型说不出的东西，比如数组的结构形态。

评审者逐条看的：五条人管规则

Pint 管不到的部分，评审者会逐条核对：

  • 每个方法、属性和常量都必须带 docblock，与可见性无关，首字母大写、以句号结尾、不超过两行。背后的逻辑是 Bagisto 的包按 Contract/Model/Proxy 分层，docblock 是评审者快速判断一个成员用途的唯一入口。
  • 类成员顺序：常量 → 属性 → 构造函数 → public → protected → private，每种可见性一个连续区块。
  • 方法体内禁止注释，PHP、Blade、JS、Vue 一律如此。一行代码需要文字解释才能看懂时，正确做法是抽取一个命名方法，让方法名自解释。
  • 所有数据库访问必须走 repository，repository 继承Webkul\Core\Eloquent\Repository，唯一被允许的例外是 DataGrid 的prepareQueryBuilder()。背后的逻辑是 Contract/Model/Proxy 的可替换性建立在这一层之上，controller 里直查 model 会破坏扩展机制。
  • 所有面向用户的字符串必须经过trans()，新 key 必须同步到全部 23 个语言目录——根lang/与各包Resources/lang/下各 23 个 locale，从ar到zh_CN。背后的逻辑是缺任何一个 locale，CI 的翻译检查直接转红。如果新增一整个 locale，还要在 Admin、Shop、Installer 三个构建里补上 vee-validate 的校验文案，这一项翻译检查命令是看不见的。

前端改动有独立的提交边界：源码在packages/Webkul/<Package>/src/Resources/assets/，构建产物落在public/themes/*/*/build/。你必须在你变更的包内部构建，绝不能从仓库根目录构建：

cd packages/Webkul/Admin && npm install && npm run build

Shop、Installer 同理，换掉包名即可。禁止提交编译后的文件。说白了，bundle 体积巨大、无法评审，还是一条向 Bagisto 夹带恶意代码的便捷通道，所以构建产物由维护者生成并提交，贡献者无需也不应提交。

PR 前检查清单：出门前必跑的四道自检关

第 1 关：vendor/bin/pint --test。过不了会怎样：CI 每次 push 都跑这个形式，风格不过关的 PR 在人工评审开始前就是红的；先用vendor/bin/pint自动修复一轮，能省一次往返。

第 2 关：vendor/bin/pest。过不了会怎样：仓库的测试栈是 Pest 5 加 PHPUnit 13，各包测试位于packages/Webkul/<Package>/tests/，CI 跑的是vendor/bin/pest --parallel并覆盖 MySQL、MariaDB、PostgreSQL 九个数据库版本；本地挂掉意味着你的修复或特性没有测试背书，CI 只会换一种方式红给你看。

第 3 关：php artisan bagisto:translations:check。过不了会怎样：只要你改过任何翻译 key，本地不过就意味着 CI 的翻译任务必红。命令实现在packages/Webkul/Core/src/Console/Commands/TranslationsChecker.php，以en为基准逐 locale 对比缺失文件、多余文件、缺失 key、结构漂移等六类问题，退出码非零即不同步；没动翻译可以跳过，但要写进 PR 描述。

第 4 关：动过哪个包，就按包跑 Playwright E2E。过不了会怎样：CI 只在 PR 带有Need Playwright Testing标签时才跑 Playwright，标签在时每次 push 都会再触发；换句话说，你不在本地验证，贴标签后的第一个红屏就是你的 PR。E2E 必须从包目录内执行，以 Admin 为例：

cd packages/Webkul/Admin && npm run test:e2e

背后的逻辑是浏览器测试成本高，所以按标签按需开启；Admin 和 Shop 需要本地有运行中的服务与种子数据，Installer 则跑在未安装的应用上。

四关跑完后，填写 PR 模板.github/PULL_REQUEST_TEMPLATE.md，在描述中如实列出你实际运行了哪些检查、跳过了哪些以及原因。

收尾动线：从认领到开 PR 的八步

  1. 在 Issue 下留言认领，等待指派；功能类变更先在 Issue 评论里对齐方案。
  2. 克隆仓库git clone https://gitcode.com/gh_mirrors/ba/bagisto，从目标发布线拉出分支issue-1234，提交主题用fix:或feat:。
  3. 动手改：前端源码只进包内src/Resources/assets/，数据库访问走 repository，用户可见字符串走trans()。
  4. 动过前端就在包目录内构建，任何情况下都不提交public/themes/*/*/build/下的产物。
  5. 运行vendor/bin/pint自动修复风格，逐条自查 docblock、成员顺序、方法内注释、repository、trans()五项。
  6. 运行vendor/bin/pest；动过翻译则运行php artisan bagisto:translations:check，key 同步到全部 23 个语言目录。
  7. 动过界面流程就在包目录运行npm run test:e2e，给 PR 贴上 Need Playwright Testing 标签。
  8. 填写 PR 模板，列出运行与跳过的检查项及原因，向切分支的那条分支开 PR。

【免费下载链接】bagistoOpen Source eCommerce & Multi-Vendor Marketplace Platform Built with Laravel for Enterprise-Scale Commerce, Supporting 10M+ SKUs项目地址: https://gitcode.com/gh_mirrors/ba/bagisto

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考