跳到内容

贡献指南

Bug 报告

为了鼓励积极协作,Laravel 强烈鼓励提交拉取请求,而不仅仅是 Bug 报告。拉取请求只有在标记为“准备审查”(而不是“草稿”状态)且新功能的所有测试均通过时才会进行审查。处于“草稿”状态的长期未激活的拉取请求将在几天后关闭。

但是,如果您提交 Bug 报告,您的问题应包含标题和问题的清晰描述。您还应尽可能多地包含相关信息和演示该问题的代码示例。Bug 报告的目标是使您自己和其他人能够轻松地重现该 Bug 并开发修复程序。

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

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

Laravel 源代码在 GitHub 上进行管理,每个 Laravel 项目都有存储库

支持问题

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

核心开发讨论

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

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

哪个分支?

所有 Bug 修复都应发送到支持 Bug 修复的最新版本(目前为 11.x)。Bug 修复绝不应发送到 master 分支,除非它们修复了仅在即将发布的版本中存在的功能。

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

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

编译后的资源

如果您提交的更改将影响已编译的文件,例如 laravel/laravel 存储库中 resources/cssresources/js 中的大多数文件,请勿提交已编译的文件。由于它们的文件很大,维护人员无法实际审查它们。这可能会被利用作为将恶意代码注入 Laravel 的一种方式。为了防御性地防止这种情况,所有编译后的文件将由 Laravel 维护人员生成和提交。

安全漏洞

如果您在 Laravel 中发现安全漏洞,请发送电子邮件给 Taylor Otwell,邮箱地址为 [email protected]。所有安全漏洞都将得到及时处理。

编码风格

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

PHPDoc

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

1/**
2 * Register a binding with the container.
3 *
4 * @param string|array $abstract
5 * @param \Closure|string|null $concrete
6 * @param bool $shared
7 * @return void
8 *
9 * @throws \Exception
10 */
11public function bind($abstract, $concrete = null, $shared = false)
12{
13 // ...
14}

当由于使用原生类型而导致 @param@return 属性变得冗余时,可以将其删除

1/**
2 * Execute the job.
3 */
4public function handle(AudioProcessor $processor): void
5{
6 //
7}

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

1/**
2 * Get the attachments for the message.
3 *
4 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
5 */
6public function attachments(): array
7{
8 return [
9 Attachment::fromStorage('/path/to/file'),
10 ];
11}

StyleCI

如果您的代码风格不完美,请不要担心!在拉取请求合并后,StyleCI 将自动将任何样式修复合并到 Laravel 存储库中。这使我们可以专注于贡献的内容,而不是代码风格。

行为准则

Laravel 行为准则源自 Ruby 行为准则。任何违反行为准则的行为都可以报告给 Taylor Otwell ([email protected])

  • 参与者应容忍对立的观点。
  • 参与者必须确保他们的语言和行为不含人身攻击和贬低个人言论。
  • 在解释他人的言语和行为时,参与者应始终假设善意。
  • 可以合理地被认为是骚扰的行为将不被容忍。

Laravel 是构建最有效率的方式
构建、部署和监控软件。