贡献指南

• 错误报告
• 支持问题
• 核心开发讨论
• 哪个分支？
• 编译后的资产
• 安全漏洞
• 编码风格
  • PHPDoc
  • StyleCI
• 行为准则

错误报告

为了鼓励积极的协作，Laravel 强烈建议提交 Pull Request，而不仅仅是错误报告。只有当 Pull Request 被标记为“准备审查”（而不是“草稿”状态）并且所有新功能的测试都通过时，才会对其进行审查。在“草稿”状态下停留时间过长且不活跃的 Pull Request 将在几天后关闭。

但是，如果你提交错误报告，你的问题应该包含标题和对问题的清晰描述。你还应该包含尽可能多的相关信息以及演示问题的代码示例。错误报告的目标是让你自己——以及其他人——更容易复制错误并开发修复方案。

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

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

Laravel 源代码在 GitHub 上进行管理，并且每个 Laravel 项目都有相应的仓库

支持问题

Laravel 的 GitHub 问题跟踪器并非旨在提供 Laravel 帮助或支持。请改用以下渠道之一

核心开发讨论

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

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

哪个分支？

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

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

**主要**的新功能或具有重大更改的功能应始终发送到 master 分支，该分支包含即将发布的版本。

编译后的资产

如果你提交的更改将影响编译文件（例如，laravel/laravel 仓库的 resources/css 或 resources/js 中的大多数文件），请不要提交编译后的文件。由于它们的大小很大，维护者无法实际对其进行审查。这可能被利用作为将恶意代码注入 Laravel 的途径。为了防御性地防止这种情况，所有编译后的文件都将由 Laravel 维护者生成并提交。

安全漏洞

如果你在 Laravel 中发现安全漏洞，请发送电子邮件到 Taylor Otwell 的邮箱 [email protected]。所有安全漏洞都将得到及时解决。

编码风格

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

PHPDoc

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

/**
 * Register a binding with the container.
 *
 * @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 属性冗余时，可以将其删除

/**
 * Execute the job.
 */
public function handle(AudioProcessor $processor): void
{
    //
}

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

/**
 * Get the attachments for the message.
 *
 * @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 ([email protected])