# 贡献导引
- [Bug 报告](#bug-reports)
- [帮助支持](#support-questions)
- [核心开发讨论](#core-development-discussion)
- [选择哪个分支？](#which-branch)
- [编译资源](#compiled-assets)
- [AI 生成的贡献](#ai-generated-contributions)
- [安全漏洞](#security-vulnerabilities)
- [代码风格](#coding-style)
    - [PHPDoc](#phpdoc)
    - [StyleCI](#styleci)
- [行为准则](#code-of-conduct)

<a name="bug-reports"></a>

## Bug 报告

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

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

请记住，创建 Bug 报告是希望有相同问题的人能够与您协作解决它。不要期望 Bug 报告会自动引发任何进展，或者其他人会迅速修复它。创建 Bug 报告有助于帮助您自己和他人开始修复问题。如果你想参与，你可以通过修复 [我们的 issue 跟踪器中列出的任何 Bug](https://github.com/issues?q=is%3Aopen+is%3Aissue+label%3Abug+user%3Alaravel) 来提供帮助。你必须通过 GitHub 身份验证才能查看 Laravel 的所有 issue。


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

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

<div class="content-list" markdown="1">

- [Laravel Application](https://github.com/laravel/laravel)
- [Laravel Art](https://github.com/laravel/art)
- [Laravel Boost](https://github.com/laravel/boost)
- [Laravel Documentation](https://github.com/laravel/docs)
- [Laravel Dusk](https://github.com/laravel/dusk)
- [Laravel Cashier Stripe](https://github.com/laravel/cashier)
- [Laravel Cashier Paddle](https://github.com/laravel/cashier-paddle)
- [Laravel Echo](https://github.com/laravel/echo)
- [Laravel Envoy](https://github.com/laravel/envoy)
- [Laravel Folio](https://github.com/laravel/folio)
- [Laravel Framework](https://github.com/laravel/framework)
- [Laravel Horizon](https://github.com/laravel/horizon)
- [Laravel Passport](https://github.com/laravel/passport)
- [Laravel Pennant](https://github.com/laravel/pennant)
- [Laravel Pint](https://github.com/laravel/pint)
- [Laravel Prompts](https://github.com/laravel/prompts)
- [Laravel Reverb](https://github.com/laravel/reverb)
- [Laravel Sail](https://github.com/laravel/sail)
- [Laravel Sanctum](https://github.com/laravel/sanctum)
- [Laravel Scout](https://github.com/laravel/scout)
- [Laravel Socialite](https://github.com/laravel/socialite)
- [Laravel Telescope](https://github.com/laravel/telescope)
- [Laravel Livewire Starter Kit](https://github.com/laravel/livewire-starter-kit)
- [Laravel React Starter Kit](https://github.com/laravel/react-starter-kit)
- [Laravel Svelte Starter Kit](https://github.com/laravel/svelte-starter-kit)
- [Laravel Vue Starter Kit](https://github.com/laravel/vue-starter-kit)

</div>



<a name="support-questions"></a>
## 帮助支持
Laravel 的 GitHub 问题跟踪器不打算提供 Laravel 帮助或支持。相反，请使用以下渠道之一：

<div class="content-list" markdown="1">

- [GitHub 讨论](https://github.com/laravel/framework/discussions)
- [Laracasts 论坛](https://laracasts.com/discuss)
- [Laravel.io 论坛](https://laravel.io/forum)
- [StackOverflow](https://stackoverflow.com/questions/tagged/laravel)
- [Discord](https://discord.gg/laravel)
- [Larachat](https://larachat.co)
- [IRC](https://web.libera.chat/?nick=artisan&channels=#laravel)

</div>

<a name="core-development-discussion"></a>
## 核心开发讨论

您可以在 Laravel 框架仓库的 [GitHub 讨论区](https://github.com/laravel/framework/discussions) 中提出新功能或改进现有 Laravel 行为的建议。如果您提出一项新功能，请愿意至少实现完成该功能所需的部分代码。

有关错误、新功能以及现有功能实现的非正式讨论，会在 [Laravel Discord 服务器](https://discord.gg/laravel) 的 `#internals` 频道中进行。Laravel 的维护者 Taylor Otwell 通常在工作日的上午 8 点至下午 5 点（UTC-06:00 或 美国 / 芝加哥）出现在该频道，其他时间则偶尔出现。

<a name="which-branch"></a>
## 哪个分支？

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

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

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

<a name="compiled-assets"></a>
## 编译资源

如果您提交的更改会影响编译后的文件（例如 `laravel/laravel` 仓库中 `resources/css` 或 `resources/js` 目录下的大部分文件），请不要提交编译后的文件。由于这些文件体积较大，维护者实际上无法对其进行审查。这可能会被利用作为向 Laravel 注入恶意代码的方式。为主动防范此类风险，所有编译后的文件将由 Laravel 维护者生成并提交。


<a name="ai-generated-contributions"></a>
## AI 生成的贡献

我们感谢提交给 Laravel 的每一个拉取请求。然而，那些主要依靠 AI 生成、未经人类审慎思考和审查的贡献是不被接受的。

如果您选择使用 AI 工具辅助您的贡献，**必须**在提交前对生成的代码进行彻底审查、测试并充分理解。

**我们绝不容忍完全由 AI 生成并批量提交的问题或拉取请求。** 此类拉取请求将不经审查直接关闭，提交者可能会被该仓库封禁。

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

<a name="security-vulnerabilities"></a>
## 安全漏洞

如果您发现 Laravel 中的安全漏洞，请发送电子邮件至 Taylor Otwell <taylor@laravel.com>。所有安全漏洞将被及时处理。


<a name="coding-style"></a>
## 代码风格
Laravel 遵循 [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md) 编码标准和 [PSR-4](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md) 自动加载标准。

<a name="phpdoc"></a>
### PHPDoc

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

```php
/**
 * 在容器中注册绑定。
 *
 * @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` 属性冗余时，可以将其移除：

```php
/**
 * 执行任务
 * [tl! remove]
 * @return void [tl! remove]
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}
```
但是，当原生类型是泛型时，请通过使用 `@param` 或 `@return` 属性指定泛型类型：

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

<a name="styleci"></a>
### StyleCI

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

<a name="code-of-conduct"></a>
## 行为准则

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

<div class="content-list" markdown="1">

-   参与者应尊重不同的观点。
-   参与者必须确保其言辞和行为不涉及人身攻击和贬低他人的言论。
-   在解释他人的言行时，参与者应始终保持良好的意图。
-   不能容忍可合理视为骚扰的行为。

</div>