貢獻指南

• 錯誤回報
• 支援問題
• 核心開發討論
• 哪個分支？
• 編譯的資產
• 安全性弱點
• 程式碼風格
  • PHPDoc
  • StyleCI
• 行為準則

錯誤回報

為鼓勵積極協作，Laravel 強烈建議提交 Pull Request，而不僅僅是錯誤回報。Pull Request 僅會在標記為「準備好審核」(而非「草稿」狀態) 且所有新功能的測試皆通過時才會進行審核。擱置中、不活躍且仍處於「草稿」狀態的 Pull Request 將在幾天後關閉。

然而，如果您提交錯誤回報，您的問題應包含標題和清晰的問題描述。您還應盡可能包含所有相關資訊以及一個能展示問題的程式碼範例。錯誤回報的目標是讓您和他人能夠輕鬆地重現該錯誤並開發修復方案。

請記住，錯誤回報是為了讓遇到相同問題的其他人能夠與您合作解決問題。不要期望錯誤回報會自動獲得任何關注，或期望其他人會立即修復它。建立錯誤回報有助於您和他人開始著手解決問題。如果您想出力，可以透過修復我們議題追蹤器中列出的任何錯誤來提供幫助。您必須通過 GitHub 驗證才能查看所有 Laravel 的議題。

如果您在使用 Laravel 時發現不正確的 DocBlock、PHPStan 或 IDE 警告，請不要建立 GitHub 議題。相反地，請提交一個 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 Homestead (建構腳本)
• 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 Vue Starter Kit

支援問題

Laravel 的 GitHub 議題追蹤器不旨在提供 Laravel 協助或支援。相反地，請使用以下其中一個管道：

• GitHub Discussions
• Laracasts 論壇
• Laravel.io 論壇
• StackOverflow
• Discord
• Larachat
• IRC

核心開發討論

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

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

哪個分支？

所有錯誤修復都應該發送到支援錯誤修復的最新版本 (目前為 12.x)。錯誤修復絕不應發送到 master 分支，除非它們修復了僅存在於即將發布版本中的功能。

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

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

編譯的資產

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

安全性弱點

如果您在 Laravel 中發現安全性弱點，請寄送電子郵件至 [email protected] 給 Taylor Otwell。所有安全性弱點都將會被迅速處理。

程式碼風格

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

如果您的程式碼風格不完美，也無需擔心！Pull Request 合併後，StyleCI 將自動把所有風格修復合併到 Laravel 儲存庫中。這讓我們能夠專注於貢獻的內容，而非程式碼風格。

行為準則

Laravel 的行為準則源自於 Ruby 的行為準則。任何對行為準則的違規都可以向 Taylor Otwell ([email protected]) 回報：

• 參與者應寬容不同意見。
• 參與者必須確保其言行沒有人身攻擊及貶低性言論。
• 在解讀他人的言行時，參與者應始終抱持良好意圖。
• 任何可被合理視為騷擾的行為都不會被容忍。