參與貢獻指南

• Bug 回報

• 支援提問

• 核心開發討論

• 要用哪個分支？

• 編譯素材

• 安全性漏洞

• Coding Style

  • PHPDoc
  • StyleCI

• 行為準則 - Code of Conduct

Bug 回報

為了鼓勵活躍的社群協作，因此 Laravel 不建議只進行 Bug 回報，更強烈建議大家提供 Pull Request。Pull Request 只有在標註為「Ready for review (可供檢閱)」 (即不在「Draft (草稿)」狀態) 且新功能的所有測試例都通過時才會被檢閱。長期放置、非活躍的「Draft」 Pull Request 會在幾天內被關閉。

不過，若要提出 Bug 回報，則 Issue 內應包含標題以及對該問題的清楚敘述。也應儘可能提供相關資訊、以及能展示此問題的範例程式碼。Bug 回報的目標就是要能讓你自己 —— 以及其他人 —— 能重現此 Bug 並著手修正。

請記得，進行 Bug 回報的目的是為了能讓其他有相同問題的人能與你一起協作來解決此問題。請不要覺得回報了 Bug 後，該 Bug 就會自動吸引到人，或是就有人自動來修正此 Bug。回報 Bug 是為了幫助你自己以及其他人能作為修正問題的出發點。若你想參與，可以協助修正任何列在我們 Issue Tracker 上的 Bug。你必須先登入 GitHub 才能檢視所有的 Laravel Issue。

若使用 Laravel 時注意到有關不適當的 DocBlock、PHPStan、或 IDE 警告，請不要建立新的 GitHub Issue。請建立 Pull Request 來修正此問題。

Laravel 的原始碼託管於 GitHub，而各個 Laravel 專案都有各自的儲存庫：

支援提問

Laravel 的 GitHub Issue Tracker 並不是用來提供 Laravel 說明或協助的。請改用下列其中一種管道：

核心開發討論

可以在 Laravel 框架存放庫的 GitHub Discussion Board 上提議新功能或是改進現有的 Laravel 行為。若要提議新功能，請至少準備好要能實作完成此功能所需的部分程式碼。

有關 Bug、新功能、以及現有功能實作的一些比較不正式的討論，會在 Laravel 的 Discord Server上的 #internals 頻道內進行。Taylor Otwell —— Laravel 的維護人員，通常會在工作日的上午 8 時至下午 5 時 (UTC-06:00 或 America/Chicago) 或是其他不定期時間出現在此頻道內。

要用哪個分支？

所有的 Bug 修正都應送交目前有支援 Bug 修正的最新版本 (目前為 11.x)。Bug 修正不該送交至 master 分支，除非要修正的功能只出現在未來的版本中。

對於目前版本有完整向下相容性的次要 (Minor) 功能，可以送交至最新的穩定分支 (目前為 11.x)。

主要 (Major) 新功能，或是包含中斷性變更的修改，則應送交至 master 分支，這個分支包含了未來的版本。

編譯素材

若要送交的修改會影響到經過編譯的檔案 (通常是 laravel/laravel 儲存庫的 resources/css 或 resources/js)，請不要簽入 (Commit) 這些編譯後的檔案。由於這些檔案的大小很大，因此無法實際被維護人員審閱，進而造成能向 Laravel 插入惡意程式碼的機會。為了避免此一問題，所有經過編譯的檔案都應由 Laravel 維護人員產生並簽入。

安全性漏洞

If you discover a security vulnerability within Laravel, please send an email to Taylor Otwell at [email protected]. All security vulnerabilities will be promptly addressed.

編碼樣式

Laravel 遵守 PSR-2 編碼標準以及 PSR-4 Autoload 標準。

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}
 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 屬性所宣告的內容與原生型別重複時，可移除這些 PHPDoc 屬性：

1/**
2 * Execute the job.
3 */
4public function handle(AudioProcessor $processor): void
5{
6    //
7}
1/**
2 * Execute the job.
3 */
4public function handle(AudioProcessor $processor): void
5{
6    //
7}

不過，若原生型別是 Generic(泛型) 時，請使用 @param 或 @return 屬性來指定 Generic 的型別：

 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}
 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

不用擔心你的編碼風格不正確！StyleCI 會在 Pull Request 被 Merge 後自動合併任何的樣式修正。這樣一來我們就能專注在參與貢獻的內容而非程式碼風格。

行為準則 - Code of Conduct

The Laravel code of conduct is derived from the Ruby code of conduct. Any violations of the code of conduct may be reported to Taylor Otwell ([email protected]):