贡献指南

• 错误报告
• 支持咨询
• 核心开发讨论
• 应该使用哪个分支？
• 编译后的资源文件
• AI 生成的贡献
• 安全漏洞
• 代码风格
  • PHPDoc
  • StyleCI
• 行为准则

错误报告

为了鼓励积极协作，Laravel 强烈建议提交 Pull Request，而不仅仅是报告 Bug。只有标记为“准备评审”（非“草稿”状态）且所有新功能测试均已通过的 Pull Request 才会得到评审。长时间处于“草稿”状态且无活动的 Pull Request 将在几天后被关闭。

如果你要提交错误报告，内容应包含标题和清晰的问题描述。你还应尽可能包含相关信息以及可重现问题的代码示例。编写错误报告的目标是让你自己及他人能够轻松地复现该 Bug 并开发出修复方案。

请记住，提交错误报告是希望遇到同样问题的他人能够与你协作解决。请不要期望错误报告会自动得到关注，也不要期望他人会立即进行修复。创建错误报告是为了帮助你自己和他人开启修复问题的路径。如果你想出一份力，可以通过修复我们在问题追踪器中列出的任何 Bug 来提供帮助。你必须登录 GitHub 才能查看 Laravel 的所有议题。

如果你在使用 Laravel 时发现不当的 DocBlock、PHPStan 或 IDE 警告，请不要创建 GitHub 议题。相反，请提交一个 Pull Request 来修复该问题。

Laravel 源代码托管在 GitHub 上，且每个 Laravel 项目都有独立的仓库

支持咨询

Laravel 的 GitHub 问题追踪器并非用于提供 Laravel 的使用帮助或技术支持。请改用以下渠道：

核心开发讨论

你可以在 Laravel 框架仓库的 GitHub 讨论区提议新功能或对现有 Laravel 行为的改进。如果你提议一个新功能，请准备好实现完成该功能所需的部分代码。

关于 Bug、新功能以及现有功能实现的非正式讨论都在 Laravel Discord 服务器的 #internals 频道进行。Laravel 的维护者 Taylor Otwell 通常会在工作日的上午 8 点至下午 5 点（UTC-06:00 或美国中部时间）出现在该频道，有时也会在其他时间随机出现。

应该使用哪个分支？

所有 Bug 修复应提交至支持 Bug 修复的最新版本（目前为 13.x）。除非修复的内容仅存在于即将发布的版本中，否则 Bug 修复绝不应提交至 master 分支。

与当前版本完全向后兼容的小型功能可以提交至最新的稳定分支（目前为 13.x）。

重大新功能或具有破坏性变更的功能应始终提交至 master 分支，该分支包含即将发布的版本。

编译后的资源文件

如果你提交的更改涉及编译后的文件（例如 laravel/laravel 仓库中 resources/css 或 resources/js 下的大多数文件），请勿提交这些编译后的文件。由于体积过大，维护者实际上无法对其进行审核。这可能被利用作为向 Laravel 植入恶意代码的途径。为了防御性地防止这种情况，所有编译后的文件都将由 Laravel 维护者生成并提交。

AI 生成的贡献

我们感谢提交给 Laravel 的每一个 Pull Request。但是，那些在没有经过深思熟虑的人工审查和考量的情况下，主要由 AI 生成的贡献是不可接受的。

如果你选择使用 AI 工具协助你的贡献，那么在提交之前，生成的结果代码必须经过你本人的彻底审查、测试和理解。

我们不会容忍大规模开启完全由 AI 生成的议题或 Pull Request。 此类 Pull Request 将在不予审查的情况下直接关闭，且贡献用户可能会被封禁。

我们鼓励贡献者熟悉现有代码库，积极参与社区互动，并提交反映出他们对所解决问题有着深刻理解和仔细考量的 Pull Request。

安全漏洞

如果你发现 Laravel 中存在安全漏洞，请发送电子邮件至 Taylor Otwell：[email protected]。所有安全漏洞都将得到及时处理。

代码风格

Laravel 遵循 PSR-2 编码规范和 PSR-4 自动加载规范。

PHPDoc

以下是一个有效的 Laravel 文档块示例。请注意，@param 属性后面跟着两个空格、参数类型、另外两个空格，最后是变量名。

 1/**
 2 * Register a binding with the container.
 3 *
 4 * @param  string|array  $abstract
 5 * @param  \Closure|string|null  $concrete
 6 * @param  bool  $shared
 7 * @return void
 8 *
 9 * @throws \Exception
10 */
11public function bind($abstract, $concrete = null, $shared = false)
12{
13    // ...
14}

当使用原生类型导致 @param 或 @return 属性冗余时，可以将它们移除。

1/**
2 * Execute the job.
3 */
4public function handle(AudioProcessor $processor): void
5{
6    // ...
7}

但是，当原生类型是泛型时，请通过使用 @param 或 @return 属性来明确泛型类型。

 1/**
 2 * Get the attachments for the message.
 3 *
 4 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 5 */
 6public function attachments(): array
 7{
 8    return [
 9        Attachment::fromStorage('/path/to/file'),
10    ];
11}

StyleCI

别担心你的代码风格不够完美！在 Pull Request 合并后，StyleCI 会自动将所有风格修复合并到 Laravel 仓库中。这使我们能够专注于贡献的内容，而不是代码风格。

行为准则

Laravel 的行为准则源自 Ruby 的行为准则。任何违反行为准则的行为都可以举报给 Taylor Otwell ([email protected])。