貢獻指南

• 錯誤報告
• 支援諮詢
• 核心開發討論
• 應該使用哪個分支？
• 編譯後的資原始檔
• AI 生成的貢獻
• 安全漏洞
• 程式碼風格
  • PHPDoc
  • StyleCI
• 行為準則

錯誤報告

為了鼓勵積極協作，Laravel 強烈建議提交 Pull Request，而不僅僅是報告 Bug。只有標記為“準備評審”（非“草稿”狀態）且所有新功能測試均已透過的 Pull Request 才會得到評審。長時間處於“草稿”狀態且無活動的 Pull Request 將在幾天後被關閉。

如果你要提交錯誤報告，內容應包含標題和清晰的問題描述。你還應儘可能包含相關資訊以及可重現問題的程式碼示例。編寫錯誤報告的目標是讓你自己及他人能夠輕鬆地復現該 Bug 並開發出修復方案。

請記住，提交錯誤報告是希望遇到同樣問題的他人能夠與你協作解決。請不要期望錯誤報告會自動得到關注，也不要期望他人會立即進行修復。建立錯誤報告是為了幫助你自己和他人開啟修復問題的路徑。如果你想出一份力，可以透過修復我們在問題追蹤器中列出的任何 Bug 來提供幫助。你必須登入 GitHub 才能檢視 Laravel 的所有議題。

如果你在使用 Laravel 時發現不當的 DocBlock、PHPStan 或 IDE 警告，請不要建立 GitHub 議題。相反，請提交一個 Pull Request 來修復該問題。

Laravel 原始碼託管在 GitHub 上，且每個 Laravel 專案都有獨立的倉庫

支援諮詢

Laravel 的 GitHub 問題追蹤器並非用於提供 Laravel 的使用幫助或技術支援。請改用以下渠道：

核心開發討論

你可以在 Laravel 框架倉庫的 GitHub 討論區提議新功能或對現有 Laravel 行為的改進。如果你提議一個新功能，請準備好實現完成該功能所需的部分程式碼。

關於 Bug、新功能以及現有功能實現的非正式討論都在 Laravel Discord 伺服器的 #internals 頻道進行。Laravel 的維護者 Taylor Otwell 通常會在工作日的上午 8 點至下午 5 點（UTC-06:00 或美國中部時間）出現在該頻道，有時也會在其他時間隨機出現。

應該使用哪個分支？

所有 Bug 修復應提交至支援 Bug 修復的最新版本（目前為 13.x）。除非修復的內容僅存在於即將釋出的版本中，否則 Bug 修復絕不應提交至 master 分支。

與當前版本完全向後相容的小型功能可以提交至最新的穩定分支（目前為 13.x）。

重大新功能或具有破壞性變更的功能應始終提交至 master 分支，該分支包含即將釋出的版本。

編譯後的資原始檔

如果你提交的更改涉及編譯後的檔案（例如 laravel/laravel 倉庫中 resources/css 或 resources/js 下的大多數檔案），請勿提交這些編譯後的檔案。由於體積過大，維護者實際上無法對其進行稽核。這可能被利用作為向 Laravel 植入惡意程式碼的途徑。為了防禦性地防止這種情況，所有編譯後的檔案都將由 Laravel 維護者生成並提交。

AI 生成的貢獻

我們感謝提交給 Laravel 的每一個 Pull Request。但是，那些在沒有經過深思熟慮的人工審查和考量的情況下，主要由 AI 生成的貢獻是不可接受的。

如果你選擇使用 AI 工具協助你的貢獻，那麼在提交之前，生成的結果程式碼必須經過你本人的徹底審查、測試和理解。

我們不會容忍大規模開啟完全由 AI 生成的議題或 Pull Request。 此類 Pull Request 將在不予審查的情況下直接關閉，且貢獻使用者可能會被封禁。

我們鼓勵貢獻者熟悉現有程式碼庫，積極參與社群互動，並提交反映出他們對所解決問題有著深刻理解和仔細考量的 Pull Request。

安全漏洞

如果你發現 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

別擔心你的程式碼風格不夠完美！在 Pull Request 合併後，StyleCI 會自動將所有風格修復合併到 Laravel 倉庫中。這使我們能夠專注於貢獻的內容，而不是程式碼風格。

行為準則

Laravel 的行為準則源自 Ruby 的行為準則。任何違反行為準則的行為都可以舉報給 Taylor Otwell ([email protected])。