貢獻指南¶

感謝您考慮為 NextPDF 貢獻程式碼！本指南適用於 10 個 LGPL 開源套件。

注意：nextpdf/pro 與 nextpdf/enterprise 為商業授權套件，不接受外部貢獻。

貢獻範圍¶

開始之前¶

尋找適合的貢獻¶

1. 瀏覽 GitHub Issues 中標記為 good first issue 的問題
2. 在提交重大變更前，先開 Issue 討論您的想法
3. Bug 修正：可以直接提交 PR，但請先確認問題尚未修正

簽署 CLA¶

開發環境設定¶

先決條件¶

# 需要工具
php 8.5+           # 帶 pcov / xdebug
composer 2+
git
make               # 執行 Makefile 任務（可選）

# Rust 工具鏈（若要修改 Spectrum）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add x86_64-unknown-linux-gnu

克隆與設定¶

# 克隆目標套件（以 core 為例）
git clone git@github.com:nextpdf-labs/nextpdf.git
cd nextpdf

# 安裝依賴（含開發依賴）
composer install

# 驗證設定
composer test       # 應全部通過
composer phpstan    # PHPStan Level 10
composer cs-check   # PSR-12 格式檢查

程式碼標準¶

PHP 規範¶

所有 PHP 程式碼必須符合：

• PSR-1：基本程式碼規範
• PSR-4：自動載入規範
• PSR-12：擴充程式碼風格指南
• declare(strict_types=1) 必須出現在每個 PHP 檔案的第一行
• 所有參數、回傳值、屬性必須有型別標注
• 類別預設為 final，除非設計上需要繼承
• 方法最多 30 行，類別最多 300 行

<?php

declare(strict_types=1);

namespace NextPDF\Core\Typography;

use RuntimeException;

final class ExampleClass
{
    public function __construct(
        private readonly string $name,
        private readonly int    $value,
    ) {}

    /**
     * @param non-empty-string $input
     * @throws RuntimeException
     */
    public function process(string $input): string
    {
        // 實作
    }
}

Rust 規範（Spectrum）¶

# 格式化
cargo fmt

# Lint（所有警告視為錯誤）
cargo clippy -- -D warnings

# 測試
cargo test

PR 流程¶

分支命名¶

feat/short-description      # 新功能
fix/issue-number-description # Bug 修正
docs/what-was-updated       # 文件更新
refactor/what-changed       # 重構（無功能變更）
test/what-is-tested         # 新增或修改測試

提交訊息規範¶

遵循 Conventional Commits：

feat(typography): add Ruby annotation support for CJK text
fix(barcode): correct EAN-13 check digit calculation
docs(api): update TextRenderer write() parameter descriptions
test(security): add PAdES B-B signature round-trip tests
perf(spectrum): reduce JIT compilation overhead in shapingEngine

禁止在提交訊息中包含：Co-Authored-By、Claude、Anthropic 等 AI 工具標記。

提交前清單¶

在提交 PR 之前，請確認：

# 1. 格式檢查
composer cs-check     # 若有錯誤：composer cs-fix

# 2. 靜態分析（必須通過 Level 10）
composer phpstan

# 3. 執行完整測試套件
composer test

# 4. 確認覆蓋率未下降
php -d pcov.enabled=1 vendor/bin/phpunit --coverage-text

# 5. Rust（如果修改了 Spectrum）
cd rust && cargo clippy -- -D warnings && cargo test

PR 格式要求¶

PR 描述必須包含：

1. 問題描述：解決了什麼問題，或實作了什麼功能
2. 解決方案：技術實作的簡要說明
3. 測試方式：如何驗證這個變更是正確的
4. Breaking Change（若有）：影響範圍與遷移指引

測試要求¶

最低覆蓋率目標：80%（新增程式碼的 PR diff 覆蓋率 ≥ 90%）

• 每個 public 方法必須有對應的測試
• Edge cases 和錯誤路徑必須有測試
• 使用 @covers 標記確保覆蓋率元資料正確（beStrictAboutCoverageMetadata=true）

/**
 * @covers \NextPDF\Core\Barcode\Encoders\Ean13Encoder::create
 * @covers \NextPDF\Core\Barcode\Encoders\Ean13Encoder::validate
 */
final class Ean13EncoderTest extends TestCase
{
    public function test_creates_valid_encoder(): void { /* ... */ }
    public function test_throws_on_invalid_data_length(): void { /* ... */ }
    public function test_throws_on_non_numeric_data(): void { /* ... */ }
    public function test_calculates_check_digit_correctly(): void { /* ... */ }
}

CI 通過條件¶

PR 合併前必須通過所有 CI 檢查：

• composer cs-check：PSR-12 格式合規
• composer phpstan：PHPStan Level 10 通過
• composer test：所有測試通過
• 覆蓋率：PR diff 覆蓋率 ≥ 90%（advisory，不阻擋 merge）
• SonarQube：無新 Bug 或安全漏洞（Critical/Blocker）

回應時間¶

• 初步回應：5 個工作天內
• 完整審核：10 個工作天內（複雜 PR 可能更長）

行為準則¶

我們採用 Contributor Covenant 行為準則。

延伸閱讀¶

• 測試指南 — PHPUnit 測試的最佳實踐
• 安全政策 — 安全漏洞的負責任揭露
• 關於 NextPDF — 設計理念與架構