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 下留言并等待被指派再动手写任何代码。一句简短的 Id like to take this 就够。认领前先检查是否已有 assignee 或已在评论区表示在处理如果认领后长时间没有动静在原帖里询问进展不要开一个竞争性的 PR。背后的逻辑是同一个 Issue 常被多人同时认领重复劳动往往到第二份 PR 到达时才被发现白白浪费别人一个晚上。闸门 2按变更类型选分支同一条分支切出、同一分支提交。当前活跃的是三条线2.4与2.5是当前发布线master是下一条发布线当前对应 2.61.x、2.1、2.2、2.3不再接收任何新工作。分支策略就是下面这张表变更类型目标分支Bug 修复受影响的发布线通常是2.5向后兼容的小改进同一条发布线主要新特性或破坏性变更master你必须从目标分支拉出工作分支并向同一条分支开 PR不要跨分支混提仓库里也没有development分支。每个修复单独一个分支按 Issue 命名例如issue-1234提交主题用 Conventional Commitsbug 修复写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 一律如此。一行代码需要文字解释才能看懂时正确做法是抽取一个命名方法让方法名自解释。所有数据库访问必须走 repositoryrepository 继承Webkul\Core\Eloquent\Repository唯一被允许的例外是 DataGrid 的prepareQueryBuilder()。背后的逻辑是 Contract/Model/Proxy 的可替换性建立在这一层之上controller 里直查 model 会破坏扩展机制。所有面向用户的字符串必须经过trans()新 key 必须同步到全部 23 个语言目录——根lang/与各包Resources/lang/下各 23 个 locale从ar到zh_CN。背后的逻辑是缺任何一个 localeCI 的翻译检查直接转红。如果新增一整个 locale还要在 Admin、Shop、Installer 三个构建里补上 vee-validate 的校验文案这一项翻译检查命令是看不见的。前端改动有独立的提交边界源码在packages/Webkul/Package/src/Resources/assets/构建产物落在public/themes/*/*/build/。你必须在你变更的包内部构建绝不能从仓库根目录构建cd packages/Webkul/Admin npm install npm run buildShop、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 的八步在 Issue 下留言认领等待指派功能类变更先在 Issue 评论里对齐方案。克隆仓库git clone https://gitcode.com/gh_mirrors/ba/bagisto从目标发布线拉出分支issue-1234提交主题用fix:或feat:。动手改前端源码只进包内src/Resources/assets/数据库访问走 repository用户可见字符串走trans()。动过前端就在包目录内构建任何情况下都不提交public/themes/*/*/build/下的产物。运行vendor/bin/pint自动修复风格逐条自查 docblock、成员顺序、方法内注释、repository、trans()五项。运行vendor/bin/pest动过翻译则运行php artisan bagisto:translations:checkkey 同步到全部 23 个语言目录。动过界面流程就在包目录运行npm run test:e2e给 PR 贴上 Need Playwright Testing 标签。填写 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），仅供参考
