貢獻指南 (Contribution Guide)

Bug 報告 (Bug Reports)

為了鼓勵積極的協作，Laravel 強烈建議提交 pull requests，而不僅僅是 bug 報告。只有當 pull requests 被標記為「ready for review」（不是「draft」狀態）且所有新功能的測試都通過時，才會被審查。停滯不活躍的 pull requests 如果留在「draft」狀態，將在幾天後被關閉。

然而，如果你提交了 bug 報告，你的 issue 應該包含標題和對問題的清楚描述。你還應該盡可能包含相關資訊和展示問題的程式碼範例。bug 報告的目標是讓你自己和其他人能夠輕鬆地重現 bug 並開發修復程式。

請記住，bug 報告的建立是希望遇到相同問題的其他人能夠與你合作解決。不要期望 bug 報告會自動有任何活動，或者其他人會立即修復它。建立 bug 報告有助於你自己和其他人開始走上修復問題的道路。如果你想要貢獻，你可以幫助修復我們 issue 追蹤器中列出的任何 bug。你必須使用 GitHub 進行驗證才能查看所有 Laravel 的 issues。

如果你在使用 Laravel 時注意到不正確的 DocBlock、PHPStan 或 IDE 警告，請不要建立 GitHub issue。相反，請提交 pull request 來修復問題。

Laravel 原始碼在 GitHub 上管理，每個 Laravel 專案都有儲存庫：

支援問題 (Support Questions)

Laravel 的 GitHub issue 追蹤器並非用於提供 Laravel 的協助或支援。請改用以下管道之一：

核心開發討論 (Core Development Discussion)

你可以在 Laravel framework 儲存庫的 GitHub discussion 討論區中提議新功能或改進現有的 Laravel 行為。如果你提議新功能，請願意實作至少部分完成該功能所需的程式碼。

關於 bugs、新功能和現有功能實作的非正式討論會在 Laravel Discord 伺服器的 #internals 頻道中進行。Laravel 的維護者 Taylor Otwell 通常在工作日的上午 8 點至下午 5 點（UTC-06:00 或 America/Chicago）在頻道中，其他時間則偶爾出現。

要使用哪個分支？ (Which Branch)

所有 bug 修復都應該發送到支援 bug 修復的最新版本（目前是 12.x）。Bug 修復絕不應該發送到 master 分支，除非它們修復的功能只存在於即將發布的版本中。

與當前版本完全向後相容的次要功能可以發送到最新的穩定分支（目前是 12.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 會在 pull requests 合併後自動將任何風格修復合併到 Laravel 儲存庫中。這讓我們可以專注於貢獻的內容而不是程式碼風格。

行為準則 (Code Of Conduct)

Laravel 的行為準則源自 Ruby 的行為準則。任何違反行為準則的行為都可以向 Taylor Otwell（taylor@laravel.com）報告：