貢獻指南

• 錯誤報告
• 支援問題
• 核心開發討論
• 選擇哪個分支？
• 編譯後的靜態資源
• AI 生成的貢獻
• 安全性漏洞
• 程式碼風格
  • PHPDoc
  • StyleCI
• 行為準則

錯誤報告

為了鼓勵積極的協作，Laravel 強烈鼓勵提交 pull request，而非僅僅是錯誤報告。pull request 必須在標記為 「ready for review」（而非處於 「draft」 狀態）且所有新功能的測試均通過後，才會被審核。長時間處於 「draft」 狀態且沒有活動的 pull request 將在幾天後被關閉。

然而，如果您提交錯誤報告，您的 issue 應包含標題和對問題的清晰描述。您還應該盡可能提供所有相關資訊以及能證明該問題的程式碼範例。錯誤報告的目標是讓您自己以及其他人能夠輕鬆地重現該錯誤並開發修正方案。

請記住，提交錯誤報告是希望遇到相同問題的人能與您共同協作解決。請不要期待錯誤報告會自動產生任何活動，或他人會主動跳出來修復它。建立錯誤報告旨在幫助您自己和他人開啟修復問題之路。如果您想幫忙，可以嘗試修復 issue 追蹤器中列出的任何錯誤。您必須通過 GitHub 認證才能查看 Laravel 的所有 issue。

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

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

• Laravel Application
• Laravel Art
• Laravel Boost
• Laravel Documentation
• Laravel Dusk
• Laravel Cashier Stripe
• Laravel Cashier Paddle
• Laravel Echo
• Laravel Envoy
• Laravel Folio
• Laravel Framework
• Laravel Horizon
• Laravel Passport
• Laravel Pennant
• Laravel Pint
• Laravel Prompts
• Laravel Reverb
• Laravel Sail
• Laravel Sanctum
• Laravel Scout
• Laravel Socialite
• Laravel Telescope
• Laravel Livewire Starter Kit
• Laravel React Starter Kit
• Laravel Svelte Starter Kit
• Laravel Vue Starter Kit

支援問題

Laravel 的 GitHub issue 追蹤器並非旨在提供 Laravel 的幫助或支援。請改用以下其中一個管道：

• GitHub Discussions
• Laracasts Forums
• Laravel.io Forums
• StackOverflow
• Discord
• Larachat
• IRC

核心開發討論

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

關於錯誤、新功能以及現有功能實作的非正式討論在 Laravel Discord 伺服器 的 #internals 頻道中進行。Laravel 的維護者 Taylor Otwell 通常在工作日的 8am-5pm (UTC-06:00 或 America/Chicago) 出現在該頻道中，其他時間則會零星出現。

選擇哪個分支？

所有 錯誤修復應發送到支援錯誤修復的最新版本（目前為 13.x）。除非修復的是僅存在於即將發布版本中的功能，否則絕不應將錯誤修復發送到 master 分支。

與目前版本完全向下相容的次要功能可以發送到最新的穩定分支（目前為 13.x）。

重大新功能或具有破壞性變更 (breaking changes) 的功能應始終發送到包含即將發布版本的 master 分支。

編譯後的靜態資源

如果您提交的變更會影響編譯後的檔案（例如 laravel/laravel 儲存庫中 resources/css 或 resources/js 的大部分檔案），請不要提交 (commit) 這些編譯後的檔案。由於其檔案體積龐大，維護者無法現實地對其進行審核。這可能會被利用為向 Laravel 注入惡意程式碼的手段。為了防禦性地防止此情況，所有編譯後的檔案將由 Laravel 維護者生成並提交。

AI 生成的貢獻

我們感謝提交給 Laravel 的每一個 pull request。然而，主要由 AI 生成且缺乏深思熟慮的人類審核與考量的貢獻是不被接受的。

如果您選擇使用 AI 工具輔助您的貢獻，在提交之前，產出的程式碼必須經過您的徹底審核、測試且完全理解。

絕不容許大量開設完全由 AI 生成的 issue 或 pull request。 此類 pull request 將在不經審核的情況下被關閉，且貢獻使用者可能會被封鎖該儲存庫。

我們鼓勵貢獻者熟悉現有的程式碼庫，與社群互動，並提交反映其自身理解以及對所解決問題經過仔細考量的 pull request。

安全性漏洞

如果您發現 Laravel 中的安全性漏洞，請發送電子郵件給 Taylor Otwell：[email protected]。所有安全性漏洞都將被迅速處理。

程式碼風格

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 request 合併後，自動將任何風格修正合併到 Laravel 儲存庫中。這讓我們能專注於貢獻的內容而非程式碼風格。

行為準則

Laravel 的行為準則衍生自 Ruby 的行為準則。任何違反行為準則的情況都可以回報給 Taylor Otwell ([email protected])：

• 參與者應對不同觀點保持包容。
• 參與者必須確保其語言和行為不包含人身攻擊或貶低他人的言論。
• 在解讀他人的言行時，參與者應始終假設對方是出於善意。
• 任何可被合理視為騷擾的行為將不被容忍。