贡献指南

Bug 报告

为了鼓励积极协作，Laravel 强烈建议提交 pull request，而不仅仅是 bug 报告。Pull request 只有在标记为"ready for review"（非"draft"状态）且所有新功能测试通过后才会被审查。长期处于"draft"状态且无活动的 pull request 将在几天后关闭。

不过，如果你要提交 bug 报告，你的 issue 应包含标题和对问题的清晰描述。你还应尽可能多地提供相关信息，以及能够演示问题的代码示例。bug 报告的目标是让你自己和他人能够轻松复现该 bug 并开发修复方案。

请记住，bug 报告的创建是希望遇到同样问题的其他人能够与你协作解决。不要期望 bug 报告会自动产生任何活动，或者他人会立即去修复它。创建 bug 报告是为了帮助你自己和他人开始解决问题。如果你想贡献力量，可以修复我们的 issue 追踪器中列出的任何 bug。你必须通过 GitHub 身份验证才能查看 Laravel 的所有 issue。

如果你在使用 Laravel 时注意到不正确的 DocBlock、PHPStan 或 IDE 警告，请不要创建 GitHub issue，而是提交一个 pull request 来修复该问题。

Laravel 源代码托管在 GitHub 上，每个 Laravel 项目都有对应的仓库：

支持问题

Laravel 的 GitHub issue 追踪器不用于提供 Laravel 帮助或支持。请使用以下渠道之一：

核心开发讨论

你可以在 Laravel 框架仓库的 GitHub 讨论板中提议新功能或改进现有 Laravel 行为。如果你提议新功能，请愿意至少实现完成该功能所需的部分代码。

有关 bug、新功能以及现有功能实现的非正式讨论在 Laravel Discord 服务器的 #internals 频道中进行。Laravel 的维护者 Taylor Otwell 通常在工作日 8am-5pm（UTC-06:00 或 America/Chicago）出现在该频道，其他时间偶尔出现。

提交到哪个分支？

所有 bug 修复应发送到支持 bug 修复的最新版本（目前是 12.x）。Bug 修复绝不应发送到 master 分支，除非它们修复了仅存在于即将发布版本中的功能。

与当前发布版本完全向后兼容的次要功能可以发送到最新稳定分支（目前是 12.x）。

主要新功能或带有破坏性变更的功能应始终发送到 master 分支，该分支包含即将发布的版本。

编译资源

如果你提交的变更会影响编译文件（如 laravel/laravel 仓库中 resources/css 或 resources/js 中的大多数文件），请不要提交编译后的文件。由于文件体积较大，维护者实际上无法对其进行审查。这可能被利用来向 Laravel 注入恶意代码。为了防范这一点，所有编译文件将由 Laravel 维护者生成并提交。

AI 生成的贡献

我们感谢每一个提交到 Laravel 的 pull request。然而，主要由 AI 生成且未经过深思熟虑的人工审查和考量的贡献是不可接受的。

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

大量提交完全由 AI 生成的 issue 或 pull request 是不被容忍的。 此类 pull request 将在不经审查的情况下关闭，贡献用户可能会被禁止访问该仓库。

我们鼓励贡献者熟悉现有代码库，参与社区互动，并提交能够反映其自身理解和对所解决问题的深思熟虑的 pull request。

安全漏洞

如果你在 Laravel 中发现安全漏洞，请发送电子邮件至 Taylor Otwell 的邮箱 taylor@laravel.com。所有安全漏洞将得到及时处理。

代码风格

Laravel 遵循 PSR-2 编码标准和 PSR-4 自动加载标准。

PHPDoc

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

php

/**
 * 向容器注册绑定。
 *
 * @param  string|array  $abstract
 * @param  \Closure|string|null  $concrete
 * @param  bool  $shared
 * @return void
 *
 * @throws \Exception
 */
public function bind($abstract, $concrete = null, $shared = false)
{
    // ...
}

当 @param 或 @return 属性由于使用了原生类型而变得冗余时，可以将其删除：

php

/**
 * 执行该 job。
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}

但是，当原生类型是泛型时，请通过 @param 或 @return 属性指定泛型类型：

php

/**
 * 获取邮件的附件。
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file'),
    ];
}

StyleCI

不必担心你的代码风格不够完美！StyleCI 会在 pull request 合并后自动将代码风格修复合并到 Laravel 仓库中。这让我们可以专注于贡献的内容，而不是代码风格。

行为准则

Laravel 的行为准则源自 Ruby 行为准则。任何违反行为准则的行为均可向 Taylor Otwell (taylor@laravel.com) 举报：

参与者应容忍不同意见。
参与者必须确保其语言和行为不含有人身攻击或贬低他人的言论。
在解读他人的言语和行为时，参与者应始终假设对方出于善意。
可合理认定为骚扰的行为将不被容忍。

贡献指南 ​

Bug 报告 ​

支持问题 ​

核心开发讨论 ​

提交到哪个分支？ ​

编译资源 ​

AI 生成的贡献 ​

安全漏洞 ​

代码风格 ​

PHPDoc ​

StyleCI ​

行为准则 ​