贡献指南

Bug Reports

为了鼓励积极的协作，Laravel 强烈鼓励使用拉取请求，而不仅仅是提交错误报告。拉取请求只有在标记为 “ready for review”（即不是 “草稿” 状态）并且所有新功能的测试通过后，才会进行审查。那些长期处于 “草稿” 状态且没有活动的拉取请求将在几天后关闭。

然而，如果您提交错误报告，报告中应包含标题和清晰的问题描述。您还应该提供尽可能多的相关信息和一个能够演示问题的代码示例。错误报告的目的是使自己和他人能够轻松重现该错误并开发修复。

记住，错误报告是为了让其它遇到相同问题的人能够与您一起合作解决它。不要指望错误报告会自动得到处理，或者其它人会主动修复它。创建错误报告的目的是帮助自己和他人开始修复问题。如果您希望参与其中，可以帮助修复 问题追踪器中列出的任何错误。您需要通过 GitHub 进行身份验证才能查看所有 Laravel 的问题。

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

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

  • Laravel Application

  • Laravel Art

  • Laravel Breeze

  • Laravel Documentation

  • Laravel Dusk

  • Laravel Cashier Stripe

  • Laravel Cashier Paddle

  • Laravel Echo

  • Laravel Envoy

  • Laravel Folio

  • Laravel Framework

  • Laravel Homestead (构建脚本)

  • Laravel Horizon

  • Laravel Jetstream

  • Laravel Passport

  • Laravel Pennant

  • Laravel Pint

  • Laravel Prompts

  • Laravel Reverb

  • Laravel Sail

  • Laravel Sanctum

  • Laravel Scout

  • Laravel Socialite

  • Laravel Telescope

  • Laravel Website

Support Questions

Laravel 的 GitHub 问题追踪器并不用于提供 Laravel 的帮助或支持。相反，您可以使用以下渠道：

  • GitHub Discussions

  • Laracasts Forums

  • Laravel.io Forums

  • StackOverflow

  • Discord

  • Larachat

  • IRC

Core Development Discussion

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

关于错误、新功能和现有功能实现的非正式讨论将在 Laravel Discord 服务器 的 #internals 频道进行。Laravel 的维护者 Taylor Otwell 通常在工作日的 8am-5pm (UTC-06:00 或 America/Chicago) 在该频道在线，其它时间偶尔也会出现。

Which Branch?

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

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

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

Compiled Assets

如果您提交的更改会影响编译后的文件，如 laravel/laravel 仓库中的 resources/css 或 resources/js 文件中的大多数文件，请不要提交编译后的文件。由于这些文件的体积较大，无法实际进行维护者的审查。这可能会被利用为将恶意代码注入 Laravel 的途径。为了防止这种情况的发生，所有编译文件将由 Laravel 维护者生成并提交。

Security Vulnerabilities

如果您发现 Laravel 中的安全漏洞，请通过电子邮件将问题报告给 Taylor Otwell ( taylor@laravel.com )。所有安全漏洞将会被及时处理。

Coding Style

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 会在拉取请求合并后自动将任何样式修复合并到 Laravel 仓库。这使我们能够专注于贡献的内容，而不是代码风格。

Code of Conduct

Laravel 的行为准则来源于 Ruby 的行为准则。任何违反行为准则的行为都可以报告给 Taylor Otwell（ taylor@laravel.com ）：

  • 参与者应容忍不同的观点。

  • 参与者必须确保他们的语言和行为没有人身攻击或贬低性评论。

  • 在解读他人言行时，参与者应始终假设对方有良好的意图。

  • 任何可以合理视为骚扰的行为都不会被容忍。