기여 가이드

버그 리포트, 문서 개선, 기능 제안, 코드 등 모든 종류의 기여를 환영합니다. 이 페이지에서는 프로세스를 요약합니다. 전체 기여자 동의서와 상세한 가이드라인은 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

풀 리퀘스트가 병합되기 전에 모든 테스트가 통과해야 합니다. CI 파이프라인은 모든 푸시에서 전체 스위트를 실행합니다.

정적 분석

코드베이스는 레벨 8(가장 엄격한 레벨)의 PHPStan으로 분석됩니다:

composer analyse

오류는 허용되지 않습니다. 변경 사항이 PHPStan 오류를 발생시키면 CI 빌드가 실패합니다.

코드 스타일 요구사항

• 모든 PHP 파일 상단에 declare(strict_types=1).
• 새로운 코드에 대한 기준선 예외 없이 PHPStan 레벨 8 준수.
• 변경 가능한 상태가 필요하지 않은 경우 readonly 클래스 선호.
• 모든 유한 값 집합에 대해 Backed 열거형 사용 (매직 스트링이나 정수 상수 금지).
• 명확성을 위해 공개 API 메서드에서 명명된 매개변수 사용.
• mixed 타입 금지 — 모든 매개변수, 반환 타입, 프로퍼티는 명시적으로 타입이 지정되어야 합니다.
• 기본적으로 final — 확장을 위해 설계되지 않은 한 클래스는 final입니다.

풀 리퀘스트 프로세스

1. 저장소를 포크하고 main에서 기능 브랜치를 생성하세요.

2. 테스트를 먼저 작성하세요 — TCPDF-Next는 TDD 지향 워크플로우를 따릅니다. 새로운 기능과 버그 수정에는 해당하는 테스트가 포함되어야 합니다.

3. 커밋을 집중적으로 유지하세요 — 커밋당 하나의 논리적 변경. 명확한 커밋 메시지를 작성하세요.

4. 푸시하기 전에 전체 검사 스위트를 실행하세요:

   composer analyse && composer test

5. main에 대해 풀 리퀘스트를 열으세요. PR 템플릿에 다음을 작성하세요:

   • 변경 사항과 그 동기에 대한 설명.
   • 관련 이슈 링크 (Closes #123 구문 사용).
   • 파괴적 변경 사항 또는 마이그레이션 노트.

6. 리뷰 피드백에 응답하세요 — 메인테이너가 변경을 요청할 수 있습니다. 각 코멘트에 대해 주소를 지정하거나 논의하세요.

버그 리포트

다음 내용과 함께 GitHub Issue를 열어주세요:

• PHP 버전 및 OS.
• TCPDF-Next 버전 (composer show yeeefang/tcpdf-next).
• 최소 재현 코드.
• 예상 동작 vs. 실제 동작.

보안 취약점

보안 문제를 공개 GitHub Issue를 통해 신고하지 마세요. 대신 GitHub 보안 권고를 사용하세요. 자세한 내용은 자주 묻는 질문을 참조하세요.

감사합니다

모든 기여가 TCPDF-Next를 더 좋게 만듭니다. 문서의 오타를 수정하든 주요 기능을 구현하든, 여러분의 시간과 노력에 진심으로 감사드립니다.