貢獻指南

我們歡迎各種形式的貢獻 — 錯誤回報、文件改進、功能提案與程式碼。本頁摘要說明流程。完整的貢獻者協議與詳細指南請參見 GitHub 上的 CONTRIBUTING.md。

開發環境設定

前置需求

需求	最低版本
PHP	8.5+
Composer	2.x
PHPUnit	12.x
PHPStan	2.x

開始

# 複製儲存庫
git clone https://github.com/yeeefang/tcpdf-next.git
cd tcpdf-next

# 安裝相依套件
composer install

# 驗證一切正常
composer test

執行測試

TCPDF-Next 使用 PHPUnit 12，分為單元測試與整合測試套件。

# 執行完整測試套件
composer test

# 只執行單元測試（快速、無 I/O）
composer test:unit

# 只執行整合測試（檔案輸出、字型載入等）
composer test:integration

所有測試必須通過才能合併 Pull Request。CI 流程在每次推送時執行完整套件。

靜態分析

程式碼庫使用 PHPStan level 8（最嚴格等級）進行分析：

composer analyse

零錯誤容忍。如果你的變更引入 PHPStan 錯誤，CI 建構將會失敗。

程式碼風格要求

• 每個 PHP 檔案頂部 declare(strict_types=1)。
• PHPStan level 8 合規 — 新程式碼不接受 baseline 例外。
• 不需要可變狀態時，優先使用唯讀類別。
• 所有有限值集合使用具值列舉（不使用魔術字串或整數常數）。
• 公開 API 方法使用具名參數以提高清晰度。
• 禁止 mixed 型別 — 每個參數、回傳型別和屬性必須明確標注型別。
• 預設 final — 除非設計為可擴展，類別一律為 final。

Pull Request 流程

1. Fork 儲存庫，從 main 建立功能分支。

2. 先寫測試 — TCPDF-Next 採用 TDD 導向工作流。新功能和錯誤修正必須包含對應的測試。

3. 保持提交聚焦 — 每個提交一個邏輯變更。撰寫清晰的提交訊息。

4. 推送前執行完整檢查套件：

   composer analyse && composer test

5. 對 main 建立 Pull Request。填寫 PR 範本：

   • 變更描述及動機。
   • 相關 Issue 連結（使用 Closes #123 語法）。
   • 任何破壞性變更或遷移注意事項。

6. 回應審查回饋 — 維護者可能要求修改。請回應或討論每則評論。

回報錯誤

建立 GitHub Issue，包含：

• PHP 版本與作業系統。
• TCPDF-Next 版本（composer show yeeefang/tcpdf-next）。
• 最小重現程式碼。
• 預期行為 vs. 實際行為。

安全漏洞

請勿透過公開 GitHub Issue 回報安全問題。請改用 GitHub Security Advisories。詳見常見問題。

感謝

每一份貢獻都讓 TCPDF-Next 變得更好。無論你修正文件中的錯字還是實作重大功能，你的時間和努力都真誠地受到感謝。