貢獻指南

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

錯誤報告

為了鼓勵積極協作，Laravel 強烈鼓勵拉取請求，而不僅僅是錯誤報告。拉取請求只有在標記為「準備好審查」（不在「草稿」狀態）且所有新功能的測試都透過時才會被審查。擱置的、非活動的拉取請求如果一直處於「草稿」狀態，將在幾天後被關閉。

但是，如果您提交錯誤報告，您的問題應包含標題和問題的清晰描述。您還應包含盡可能多的相關資訊以及展示問題的程式碼範例。錯誤報告的目標是讓您自己和其他人都能輕鬆地複現錯誤並開發修復。

請記住，錯誤報告的建立是為了讓其他遇到相同問題的人能夠與您協作解決它。不要期望錯誤報告會自動看到任何活動，或期望其他人會跳出來修復它。建立錯誤報告是為了幫助您自己和其他人開始解決問題。如果您想貢獻，您可以透過修復我們問題追蹤器中列出的任何錯誤來提供幫助。您必須使用 GitHub 進行身份驗證才能查看 Laravel 的所有問題。

如果您在使用 Laravel 時注意到不當的 DocBlock、PHPStan 或 IDE 警告，請不要建立 GitHub 問題。相反，請提交拉取請求來修復問題。

Laravel 原始碼在 GitHub 上管理，每個 Laravel 項目都有自己的儲存庫：

技術支援問題

Laravel 的 GitHub 問題追蹤器不應用於提供 Laravel 幫助或技術支援。相反，請使用以下其中一個頻道：

核心開發討論

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

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

哪個分支？

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

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

主要新功能或具有破壞性變更的功能應始終發送到 master 分支，該分支包含即將發布的版本。

編譯資源

如果您提交的更改將影響編譯檔案，例如 laravel/laravel 儲存庫中 resources/css 或 resources/js 中的大多數檔案，請不要提交編譯檔案。由於它們體積龐大，維護者實際上無法審查它們。這可能被利用作為將惡意程式碼注入 Laravel 的方式。為了防禦性地防止這種情況，所有編譯檔案將由 Laravel 維護者生成和提交。

AI 生成的貢獻

我們感謝提交給 Laravel 的每個拉取請求。但是，未經深思熟慮的人工審查和考慮而主要由 AI 生成的貢獻是不可接受的。

如果您選擇使用 AI 工具來協助您的貢獻，產生的程式碼必須在提交前由您徹底審查、測試和理解。

大量開啟完全由 AI 生成的問題或拉取請求是不可接受的。此類拉取請求將未經審查即被關閉，並且貢獻使用者可能會被封鎖存取該儲存庫。

我們鼓勵貢獻者熟悉現有程式碼庫、與社群互動，並提交反映自己理解和仔細考慮所解決問題的拉取請求。

安全性漏洞

如果您在 Laravel 中發現安全性漏洞，請發送電子郵件至 Taylor Otwell 的 taylor@laravel.com。所有安全性漏洞將會被迅速處理。

程式碼風格

Laravel 遵循 PSR-2 程式碼標準和 PSR-4 自動載入標準。

PHPDoc

以下是有效的 Laravel 文件區塊範例。請注意，@param 屬性後跟兩個空格、參數類型、再兩個空格，最後是變數名稱：

/**
 * 在容器中註冊綁定。
 *
 * @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 屬性冗餘時，可以將其移除：

/**
 * 執行任務。
 * [tl! remove]
 * @return void [tl! remove]
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}

但是，當原生類型是泛型時，請透過使用 @param 或 @return 屬性指定泛型類型：

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

StyleCI

不要擔心您的程式碼風格不夠完美！StyleCI 將在拉取請求合併後自動將任何風格修復合併到 Laravel 儲存庫中。這使我們能夠專注於貢獻的內容而不是程式碼風格。

行為準則

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