贡献指南

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

错误报告

为了鼓励积极协作，Laravel 强烈鼓励提交拉取请求，而不仅仅是错误报告。拉取请求只有在标记为“准备审查”（非“草稿”状态）且所有新功能的测试都通过时才会被审查。长时间处于“草稿”状态且不活跃的拉取请求将在几天后关闭。

但是，如果你提交了错误报告，你的问题应包含一个标题和对问题的清晰描述。你还应包含尽可能多的相关信息以及演示该问题的代码示例。错误报告的目标是让你自己和其他人能够轻松地复现该错误并制定修复方案。

请记住，创建错误报告是希望遇到相同问题的其他人能够与你合作解决它。不要期望错误报告会自动产生任何活动，或者其他人会立即修复它。创建错误报告有助于帮助你自己和其他人走上解决问题的道路。如果你想参与进来，你可以通过修复我们问题跟踪器中列出的任何错误来提供帮助。你必须通过 GitHub 身份验证才能查看 Laravel 的所有问题。

如果你在使用 Laravel 时注意到不正确的 DocBlock、PHPStan 或 IDE 警告，请不要创建 GitHub 问题。相反，请提交一个拉取请求来修复该问题。

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

• Laravel 应用
• Laravel 标志资源
• Laravel Boost
• Laravel 文档
• Laravel Dusk
• Laravel Cashier Stripe
• Laravel Cashier Paddle
• Laravel Echo
• Laravel Envoy
• Laravel Folio
• Laravel 框架
• Laravel Horizon
• Laravel Passport
• Laravel Pennant
• Laravel Pint
• Laravel Prompts
• Laravel Reverb
• Laravel Sail
• Laravel Sanctum
• Laravel Scout
• Laravel Socialite
• Laravel Telescope
• Laravel Livewire 启动套件
• Laravel React 启动套件
• Laravel Svelte 启动套件
• Laravel Vue 启动套件

支持问题

Laravel 的 GitHub 问题跟踪器不用于提供 Laravel 帮助或支持。请改用以下渠道之一：

• GitHub 讨论
• Laracasts 论坛
• Laravel.io 论坛
• StackOverflow
• Discord
• Larachat
• IRC

核心开发讨论

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

关于错误、新功能和现有功能实现的非正式讨论在 Laravel Discord 服务器的 #internals 频道进行。Laravel 的维护者 Taylor Otwell 通常在工作日早上 8 点到下午 5 点（UTC-06:00 或 America/Chicago）出现在该频道，其他时间偶尔出现。

该选哪个分支？

所有错误修复应提交到支持错误修复的最新版本（当前为 13.x）。错误修复绝不应提交到 master 分支，除非它们修复的功能仅存在于即将发布的版本中。

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

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

编译后的资源文件

如果你提交的更改会影响编译后的文件，例如 laravel/laravel 仓库中 resources/css 或 resources/js 里的大部分文件，请不要提交编译后的文件。由于它们体积庞大，维护者无法实际审查。这可能被利用作为向 Laravel 注入恶意代码的方式。为了主动防止这种情况，所有编译后的文件将由 Laravel 维护者生成并提交。

AI 生成的贡献

我们感谢每一个向 Laravel 提交的拉取请求。然而，未经深思熟虑的人工审核和考量、主要由 AI 生成的贡献是不可接受的。

如果您选择使用 AI 工具来协助您的贡献，那么在提交之前，生成的代码必须由您进行彻底的审查、测试和理解。

我们绝不容忍大量创建完全由 AI 生成的问题或拉取请求。 此类拉取请求将被关闭且不予审查，贡献者可能会被该仓库封禁。

我们鼓励贡献者熟悉现有的代码库，与社区互动，并提交能够体现他们对所解决问题有着自身理解和审慎考虑的拉取请求。

安全漏洞

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

编码风格

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

PHPDoc

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

/**
 * 向容器注册一个绑定。
 *
 * @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 属性冗余时，可以将其删除：

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

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

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

StyleCI

如果你的代码风格不完美，请不要担心！StyleCI 会在拉取请求合并后自动将任何样式修复合并到 Laravel 仓库中。这使我们能够专注于贡献的内容，而不是代码风格。

行为准则

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

• 参与者应容忍对立的观点。
• 参与者必须确保其言辞和行为不涉及人身攻击和贬低他人的言论。
• 在解读他人的言行时，参与者应始终假定其意图是善意的。
• 任何可合理视为骚扰的行为将不被容忍。