贡献导引

• Bug 报告
• 帮助支持
• 核心开发讨论
• 选择哪个分支？
• 编译资源
• AI 生成的贡献
• 安全漏洞
• 代码风格
  • PHPDoc
  • StyleCI
• 行为准则

Bug 报告

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

不过，如果你提交 Bug 报告，你的问题（issue）应包含标题和清晰的问题描述。你还应尽可能提供相关信息和演示问题的代码示例。Bug 报告的目的是使自己和其他人能够轻松地复制 Bug 并开发修复程序。

请记住，创建 Bug 报告是希望有相同问题的人能够与您协作解决它。不要期望 Bug 报告会自动引发任何进展，或者其他人会迅速修复它。创建 Bug 报告有助于帮助您自己和他人开始修复问题。如果你想参与，你可以通过修复 我们的 issue 跟踪器中列出的任何 Bug 来提供帮助。你必须通过 GitHub 身份验证才能查看 Laravel 的所有 issue。

如果你在使用 Laravel 时注意到不适当的 DocBlock、PHPStan 或 IDE 警告，请不要创建 GitHub issue，而是提交拉取请求 ⌈PR⌋ 以解决问题。

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

帮助支持

Laravel 的 GitHub 问题跟踪器不打算提供 Laravel 帮助或支持。相反，请使用以下渠道之一：

核心开发讨论

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

有关错误、新功能以及现有功能实现的非正式讨论，会在 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 的每一个拉取请求。然而，那些主要依靠 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 属性冗余时，可以将其移除：

/**
 * 执行任务
 * [tl! remove]
 * @return void [tl! remove]
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}

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

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

StyleCI

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

行为准则

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

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/laravel/13.x/co...

译文地址：https://learnku.com/docs/laravel/13.x/co...