Bagisto 贡献指南：分支策略、代码风格与提 PR 前的完整质量检查实战- 惊觉

【免费下载链接】bagisto

Open Source eCommerce & Multi-Vendor Marketplace Platform Built with Laravel for Enterprise-Scale Commerce, Supporting 10M+ SKUs

项目地址： https://gitcode.com/gh_mirrors/ba/bagisto

点击查看免费下载

本指南以 Bagisto 仓库根目录的 CONTRIBUTING.md 为核心骨架，系统讲解如何以正确的方式向这个基于 Laravel 的开源电商平台提交代码：从认领 Issue、选择目标分支，到遵循 Laravel Pint 代码风格、编写规范 PHPDoc，再到提交 Pull Request 前必须通过的测试与翻译检查。读完本文，你将掌握一套可直接落地执行的贡献工作流，并理解每一条规则背后的仓库实现依据。

动工之前：先认领 Issue，不要直接写代码

Bagisto 的贡献流程有一条硬性前置规则：在 Issue 下留言并等待被指派（assign），再开始写任何代码。这条规则针对一个真实痛点——同一个 Issue 常常被多人同时认领，直到第二份 Pull Request 到达时才发现重复劳动。因此贡献指南建议，一句简短的 "I'd like to take this" 就足够，却能为别人省下一个晚上的时间。

在认领前，需要先检查两点：

是否已有人被指派，或是否已有人在评论区表示正在处理；
如果 Issue 已被认领但长时间没有动静，应该在原帖中询问进展，而不是直接开一个竞争性的 Pull Request。

对于新功能（feature），要求在动手实现之前就在 Issue 里达成方案共识。指南特别提醒：一个"惊喜式"到达的 Pull Request，被拒绝的更可能是方向问题（direction）而非代码质量问题。

Bug 报告：鼓励"用 PR 说话"

Bagisto 明确鼓励以 Pull Request 的形式提交 bug 修复，而不仅是提交 bug 报告——一个 bug 报告本身也可以表现为"包含一个失败测试用例的 Pull Request"。

一份合格的 bug 报告必须具备：

一个清晰的标题（title）；
清楚的描述（description）；
你所在的版本号（version）；
足够复现问题的细节（reproduce），需要时附上代码示例。

其目标是让别人能够复现该 bug，并据此构建修复方案。这条规则与仓库中丰富的测试基建相呼应：例如 Admin 包在 packages/Webkul/Admin/tests 下同时维护着 Feature 测试（Pest/PHPUnit）和 Playwright E2E 测试，为"先写失败测试再修 bug"的流程提供了现成框架。

分支策略：2.4 修 bug，master 放新特性

Bagisto 的活跃分支有两条：

2.4：当前发布线（current release line）；
master：下一条发布线（next release line，当前对应 2.5）。

更早的分支（1.x、2.1、2.2、2.3）不再接收任何新工作。分支归属的规则如下：

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

操作要求是：从目标分支拉出你的工作分支，并向着同一条分支打开 Pull Request。换言之，修 2.4 的 bug 就从 2.4 切分支、提 PR 也指向 2.4，不要跨分支混提。

核心开发思路：在 Issue 里讨论，用最小实现展示方案

指南对功能提案有一个务实要求：提出新功能时，至少实现足够展示解决方案形态（shape of the solution）的部分，而不是只抛一个空泛想法。对 bug、新功能以及现有功能实现方案的非正式讨论，都发生在对应 Issue 的评论中。这与"动工前先达成共识"的规则相互配合，形成一个闭环：方向在 Issue 中敲定，方案雏形用最小实现落地，最终以完整 PR 提交评审。

编译资源：禁止提交编译产物

Bagisto 的前后端源码分离有着严格的提交边界：

前端源码位于 packages/Webkul/<Package>/src/Resources/assets/；
构建产物输出到 public/themes/*/*/build/。

不要提交编译后的文件。指南给出的理由非常具体且具有安全意义：编译后的 bundle 体积巨大、实际上无法被评审，而且是向 Bagisto 注入恶意代码的便捷途径——因此这些产物由维护者（maintainers）负责生成并提交，贡献者无需也不应提交。

构建命令必须在发生变更的包内部执行，绝不能从仓库根目录执行：

cd packages/Webkul/Admin && npm install && npm run build   # or Shop, or Installer

这里的 Admin、Shop、Installer 三个包各自维护独立的 package.json、vite.config.js、tailwind.config.js 与 postcss.config.cjs，印证了"按包构建"的约定。以 Admin 包为例，其前端源码目录 packages/Webkul/Admin/src/Resources/assets 下包含 css/、fonts/、images/、js/、locales/ 等子目录，构建配置则见 packages/Webkul/Admin/vite.config.js。仓库根目录的 package.json 仅用于项目级依赖（如 @playwright/test、vite），并不承担主题包的编译任务。

代码风格：Laravel Pint + laravel 预设

Bagisto 使用 Laravel Pint，并采用 laravel 预设，配置见仓库根目录的 pint.json（内容即为 {"preset": "laravel"}）。提交 PR 前必须运行 Pint，因为 CI 执行的正是同一项检查：

vendor/bin/pint          # fix 自动修复
vendor/bin/pint --test   # confirm; 这是 CI 实际使用的形式

两个命令的区别：vendor/bin/pint 直接改写文件以修复风格问题；vendor/bin/pint --test 只检查不修改，返回非零退出码即表示存在风格问题，CI 用的就是后者。

注意 Pint 不会格式化 .blade.php，Blade 模板的风格需要手工把握。这解释了为什么 Blade 文件虽然存在却不在 Pint 检查范围内。

审查者会额外要求的人工规则

Pint 无法强制执行的规则，将由代码评审者逐一核对：

每个方法和属性都要带 docblock，无论其可见性（public/protected/private）；
类成员顺序：常量 → 属性 → 构造函数 → public → protected → private；
方法体内禁止注释——无论是 PHP、Blade、JS 还是 Vue。如果一行代码需要文字解释才能看懂，正确做法是抽取一个命名方法，让方法名自解释；
所有数据库访问必须走 repository，唯一例外是 DataGrid 的 prepareQueryBuilder()。这条规则与仓库的架构一致：各包下均有独立的 Repositories/ 目录，例如 packages/Webkul/Core/src/Repositories；
所有面向用户的字符串必须经过 trans()，并且 key 要同步添加到全部 22 个语言目录中。

关于"22 个语言目录"，仓库根目录 lang 下确实维护着 ar、bn、ca、de、en、es、fa、fr、he、hi_IN、id、it、ja、nl、pl、pt_BR、ro、ru、sin、tr、uk、zh_CN 共 22 个语言包，与指南中"all 22 locales"的说法完全对应。

PHPDoc 规范：类型交给签名，形状交给注解

Bagisto 有一套自己的 docblock 书写约定，指南给出了一个来自 CoreServiceProvider 的真实方法示例作为标准模板：

/**
 * Register a service with CoreServiceProvider.
 *
 * @param  string|array  $loader
 * @param  \Closure|string|null  $concrete
 * @param  bool  $shared
 * @return void
 *
 * @throws \Exception
 */
protected function registerFacades($loader, $concrete = null, $shared = false)
{
    //
}

注意格式细节：@param 后跟两个空格、类型、再跟两个空格、然后是变量名：

@param  string|array  $loader
       ↑两个空格     ↑两个空格

核心原则是：类型信息属于函数签名（凡语言本身能表达的类型都应写进签名），@param/@return 只用来补充原生类型无法表达的信息，例如数组的结构形态（shape of an array）。

打开 Pull Request 之前的完整检查清单

第一步：三项本地验证

指南在 PR 前给出三条命令，分别覆盖代码风格、单元/功能测试与多语言一致性：

vendor/bin/pint --test                       # code style 代码风格
vendor/bin/pest                              # tests 测试
php artisan bagisto:translations:check       # all 22 locales, if you touched any 若改动过任何翻译

测试框架方面，仓库 composer.json 的 require-dev 中声明了 pestphp/pest: ^3.0、pestphp/pest-plugin-laravel: ^3.0 与 phpunit/phpunit: ^11.0，说明 pest 是项目主测试命令；同时各包的 tests/ 目录（如 packages/Webkul/Admin/tests）也印证了测试即仓库一部分的事实。
翻译检查命令 bagisto:translations:check 的底层实现位于 packages/Webkul/Core/src/Console/Commands/TranslationsChecker.php，其命令签名为：

bagisto:translations:check
    {--locale= : 仅针对某个 locale 与 EN 对比}
    {--package= : 仅检查某个包}
    {--details : 显示详细错误信息}

该命令以 en 为基准（BASE_LOCALE = 'en'），扫描根 lang 目录与 packages/Webkul 下各包的 src/Resources/lang（或 resources/lang）目录，逐 locale 对比检查六类问题：缺失的 locale 文件夹、缺失的文件、多余的文件（不在 EN 中）、缺失的 key、多余的 key、与 EN 不一致的文件结构（缩进、空行、key 位置逐行比对）。运行 --details 可看到带行号的具体 key 差异，命令退出码非零即表示有翻译不同步，因此它非常适合作为 CI 或 pre-commit 检查。

第二步：按包运行端到端测试

端到端（E2E）测试按包运行，并且要从该包的目录内执行，例如 Admin 包：

cd packages/Webkul/Admin && npx playwright test --config=tests/e2e-pw/playwright.config.ts

E2E 配置见 packages/Webkul/Admin/tests/e2e-pw/playwright.config.ts，其中的关键行为包括：测试目录为 ./tests，用例超时 60 秒、断言超时 20 秒，workers: 1（串行执行），失败时保留整页截图（screenshot: "only-on-failure"）、视频与 trace，baseURL 取自 .env 中的 APP_URL，并在 chromium（Desktop Chrome）项目上运行——这些配置意味着 E2E 需要本地已启动的 Bagisto 实例配合。

第三步：CI 中的 E2E 触发机制

E2E 在 CI 中的触发有一套标签（label）机制：Pull Request 只有在带上 Need Playwright Testing 标签后才运行 Playwright 测试；只要标签还在，之后对 PR 的每次 push 都会再次触发。也就是说，E2E 是"按需开启"的，避免了对每个 PR 都跑一遍昂贵的浏览器测试。

第四步：在 PR 描述中如实声明

最后，指南要求在 PR 描述中说明你实际运行了以上哪些检查，跳过了哪些并说明原因。这既是对评审者的负责，也是信任机制的组成部分——CI 与人工检查共同把关，但贡献者自报的检查范围仍是评审流程的重要输入。

总结：一次合规贡献的完整动线

把上述规则串成一条可执行的工作流：

在 Issue 下留言认领，等待指派；功能类变更先对齐方案方向；
根据变更类型选定目标分支（bug 修复 → 2.4；新特性/破坏性变更 → master），从该分支切出工作分支；
在对应包目录内修改前端源码并按包构建（cd packages/Webkul/Admin && npm install && npm run build），不提交任何编译产物；
代码风格用 Pint 的 laravel 预设自动修复（vendor/bin/pint），Blade 手工排布，人工遵守 docblock、成员顺序、禁方法内注释、数据库走 repository、字符串走 trans() 等规则；
按规范书写 PHPDoc（@param 双空格格式），类型交给签名；
开 PR 前跑 vendor/bin/pint --test、vendor/bin/pest，改动过翻译则补跑 php artisan bagisto:translations:check；
需要时在包目录内运行 Playwright E2E，并在 PR 描述中如实声明运行/跳过的检查项。

这套流程的每一条规则都能在仓库中找到对应物——pint.json 的预设、TranslationsChecker.php 的六类检查逻辑、playwright.config.ts 的串行与失败取证配置，以及 composer.json 中声明的 Pest 测试栈——照着本文实践，即可让你的 PR 在到达评审者之前就满足 Bagisto 的全部硬性门槛。

【免费下载链接】bagisto

Open Source eCommerce & Multi-Vendor Marketplace Platform Built with Laravel for Enterprise-Scale Commerce, Supporting 10M+ SKUs

项目地址： https://gitcode.com/gh_mirrors/ba/bagisto

点击查看免费下载

上一篇：深度解析TexasSolver高性能架构：德州扑克GTO求解器核心技术优化揭秘

下一篇：从手动打字到AI代劳：STS-Bcut如何让字幕制作效率飙升10倍

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/gitblog_00774/article/details/161594917

Bagisto 贡献指南：分支策略、代码风格与提 PR 前的完整质量检查实战

【免费下载链接】bagisto

动工之前：先认领 Issue，不要直接写代码

Bug 报告：鼓励"用 PR 说话"

分支策略：2.4 修 bug，master 放新特性

核心开发思路：在 Issue 里讨论，用最小实现展示方案

编译资源：禁止提交编译产物

代码风格：Laravel Pint + laravel 预设

审查者会额外要求的人工规则

PHPDoc 规范：类型交给签名，形状交给注解

打开 Pull Request 之前的完整检查清单

第一步：三项本地验证

第二步：按包运行端到端测试

第三步：CI 中的 E2E 触发机制

第四步：在 PR 描述中如实声明

总结：一次合规贡献的完整动线

【免费下载链接】bagisto

评论

评论列表

微信小程序

QQ小程序

关于作者

Bagisto 贡献指南：分支策略、代码风格与提 PR 前的完整质量检查实战

【免费下载链接】bagisto

动工之前：先认领 Issue，不要直接写代码

Bug 报告：鼓励"用 PR 说话"

分支策略：2.4 修 bug，master 放新特性

核心开发思路：在 Issue 里讨论，用最小实现展示方案

编译资源：禁止提交编译产物

代码风格：Laravel Pint + laravel 预设

审查者会额外要求的人工规则

PHPDoc 规范：类型交给签名，形状交给注解

打开 Pull Request 之前的完整检查清单

第一步：三项本地验证

第二步：按包运行端到端测试

第三步：CI 中的 E2E 触发机制

第四步：在 PR 描述中如实声明

总结：一次合规贡献的完整动线

【免费下载链接】bagisto

相关推荐

Moto 贡献指南：PR 提交前的完整检查清单与质量保障流程

libvips 贡献指南：分支策略、clang-format 代码风格、Backport 自动化与 AI 贡献政策

WasmEdge 代码贡献规范：编码风格、提交信息与 CI 检查的完整实践指南

评论

评论列表

微信小程序

QQ小程序

关于作者