버전 관리, 안정성, 지원 중단 및 지원 정책

한눈에 보기

모든 NextPDF 문서 페이지는 프런트매터에 수명 주기 필드를 담고 있습니다. stability, since, deprecated_since, replaced_by, version_lifecycle, 그리고 eol_date입니다. 이 필드들은 이미 지원 계약을 인코딩하고 있습니다. 이 페이지는 그 계약을 한곳에 명시하여 프로덕션 팀이 어떤 페이지의 메타데이터든 읽고 버전 고정의 위험을 평가할 수 있도록 합니다.

NextPDF는 릴리스 번호에 Semantic Versioning 2.0.0을, 변경 로그 생성에 Conventional Commits 1.0.0을 따릅니다. 서비스 공급자 인터페이스(NextPDF\Contracts 및 NextPDF\Event의 공개 계약)도 동일한 규칙을 따릅니다. 계약별 @stability 태그의 작동 방식은 SPI 안정성 규칙을 참고하십시오. 이 페이지는 SPI 규칙이 특수화하는 더 넓은 정책입니다.

NextPDF의 Semantic Versioning

릴리스 버전은 MAJOR.MINOR.PATCH입니다. 바뀌는 자리가 코드에서 무엇이 바뀔 수 있는지 알려 줍니다.

증가	의미	깨질 수 있는 것
Major (`3.x` → `4.0.0`)	호환성을 깨는 변경이 허용됩니다.	`stable` 계약의 시그니처가 바뀌거나 제거될 수 있고, 이전 major에서 표시된 지원 중단 심볼이 삭제될 수 있으며, 기본 동작이 바뀔 수 있습니다.
Minor (`6.0` → `6.1.0`)	하위 호환되는 추가입니다.	`stable` 계약에는 아무것도 없습니다. 게시된 안정 인터페이스는 새로운 필수 메서드를 추가하지 않습니다. 성장은 새 계약/인터페이스, 구체 클래스의 선택적 메서드, 그리고 기본값이 있는 새 생성자/구성 옵션에서 나옵니다. `experimental` 계약은 여기서 먼저 지원 중단 공지와 함께 바뀔 수 있습니다.
Patch (`4.0.0` → `3.2.1`)	하위 호환되는 버그 수정입니다.	의도된 것은 없습니다. 동작이 문서화된 계약을 향해 수렴합니다.

stable 표면에 대한 실용적 규칙은 이렇습니다. ^3.2와 같은 Composer 제약은 해당 major 라인의 모든 minor 및 patch 릴리스를 호환성을 깨는 변경 없이 받습니다. 호환성을 깨는 변경은 major 경계에서만 발생합니다.

{
    "require": {
        "nextpdf/core": "^3.2"
    }
}

experimental 계약에 의존할 때는 더 엄격하게 고정하십시오(예: ~3.2.0). experimental 계약은 minor 릴리스에서 바뀔 수 있기 때문입니다.

안정성 레이블

페이지의 stability 필드와 계약 소스의 @stability 태그는 동일한 어휘를 사용합니다. 레이블은 호환성 약속의 강도를 명시합니다.

레이블	보장하는 것	바뀌는 시점
`stable`	프로덕션 준비 완료. 안전하게 의존할 수 있습니다. minor나 patch 릴리스에서 호환성을 깨는 변경이 없습니다. 안정 인터페이스(예: `NextPDF\Contracts` SPI)는 minor나 patch에서 새로운 필수 메서드를 추가하지 않습니다 — 하위 호환되는 성장은 새 계약, 구체 클래스의 선택적 메서드, 또는 기본값이 있는 생성자/구성 옵션을 통해 도착합니다.	major 릴리스에서만.
`beta`	기능은 완성되어 사용 가능하지만, 표면이 아직 고정되지 않았습니다. 고정 측면에서는 `experimental`처럼 취급하십시오 — 래핑하거나 엄격하게 고정하십시오.	minor 릴리스에서 먼저 지원 중단 공지와 함께 바뀔 수 있습니다.
`experimental`	사용 가능하지만 명시적으로 고정되지 않았습니다. NextPDF는 공개 계약이 아직 변할 수 있는 동안에도 테스트된 엔진 구현을 출시할 수 있습니다.	minor 릴리스에서 먼저 지원 중단 공지와 함께 바뀔 수 있습니다.
`deprecated`	제거 예정. 페이지나 계약이 대체 대상과 제거되는 major를 명시합니다.	다음 major에서 제거됩니다. minor나 patch에서는 절대 아닙니다.

스트리밍 계약 NextPDF\Contracts\CursorInterface와 NextPDF\Contracts\StreamingWriterInterface는 experimental 표면의 실제 예입니다. NextPDF는 최종적이고 테스트된 구현을 출시하지만, 공개 계약은 여전히 minor 릴리스에서 바뀔 수 있습니다. 프로덕션에서 그런 계약에 의존하기 전에 엄격하게 고정하거나 자체 어댑터 뒤에 래핑하십시오.

지원 중단 수명 주기

지원 중단은 정의된 네 단계 경로입니다. 항상 대체 대상을 명시하며, 제거는 항상 major 경계로 연기됩니다.

표시. 소유자가 계약에 @stability deprecated(또는 페이지에 deprecated_since)를 설정하고, 대체 대상과 제거 major를 기록합니다. 페이지에서 deprecated_since는 지원 중단을 도입한 버전이고 replaced_by는 정규 후속 경로입니다.
공지. 지원 중단은 그것을 표시하는 릴리스의 변경 로그에 공지됩니다.
중첩. 지원 중단된 표면과 그 대체 대상은 최소 한 번의 minor 릴리스 동안 공존하므로, 전환의 날(flag day) 없이 마이그레이션할 수 있습니다.
제거. 표면은 명시된 major 릴리스에서 제거됩니다. 제거는 minor나 patch 릴리스에서는 절대 일어나지 않습니다.

전체 수명 주기를 완주한 페이지 수준 예시로, 레거시 /docs/cookbook/php/sign-pades/ 레시피는 deprecated_since: "3.0.0"과 replaced_by: /docs/cookbook/php/sign-pades-b-b/로 표시되어 중첩 기간 동안 후속 레시피와 공존하다가 이후 제거되었습니다 — 옛 URL은 이제 후속 레시피로 향하는 영구 리디렉션으로 응답하므로, deprecated로 표시되었던 페이지를 대상으로 작성된 링크는 제거 이후에도 계속 작동합니다.

표면이 deprecated로 표시되는 즉시 마이그레이션을 계획하십시오. 대체 대상이 항상 명시되고 둘이 최소 한 번의 minor 동안 중첩되므로, 제거하는 major가 도착하기 전에 이동할 수 있습니다.

버전 수명 주기 및 보안 지원

version_lifecycle 필드는 문서화된 버전 라인이 어떻게 유지보수되는지 분류합니다. 값은 다음과 같습니다.

`version_lifecycle`	의미	받는 것
`active`	활발히 개발 중인 현재 라인.	기능, 수정, 그리고 보안 수정.
`lts`	장기 지원 라인.	지원 기간 동안의 수정과 보안 수정.
`maintenance`	활발한 개발은 지났으나 여전히 유지보수됨.	보안 수정과 심각한 버그 수정.
`frozen`	추가 기능 변경이 계획되지 않음.	해당되는 경우에 한해 보안 수정만.
`eol`	수명 종료.	없음. 업그레이드가 필요합니다.

라인이 수명 종료에 도달하면 eol_date가 그 날짜(ISO 8601, YYYY-MM-DD)를 기록합니다. version_lifecycle: eol과 과거의 eol_date를 가진 페이지는 그 라인에서 벗어나야 한다는 신호입니다. 보안 수정을 포함한 어떤 수정도 더 이상 받지 않습니다.

이는 정책 선언이지 달력상의 약속이 아닙니다. 필드는 라인이 어떤 지원 등급에 있는지 알려 줍니다. 특정 수정을 담은 구체적인 버전에 대해서는 변경 로그와 릴리스 노트를 참고하십시오. 보안 수정은 수명 주기에 여전히 보안 수정을 포함하는 라인(active, lts, maintenance)에는 백포트되지만, frozen-without-applicability나 eol로 표시된 라인에는 백포트되지 않습니다.

PHP 버전 지원 범위

NextPDF Core는 PHP >=8.4 <9.0을 요구합니다. 그 범위는 엔진의 composer.json에 선언되어 있으며 단일 진실 공급원입니다. 프리미엄 패키지(nextpdf/pro, nextpdf/enterprise)는 동일한 범위를 요구합니다.

하한(>=8.4)은 최소 런타임입니다. 이를 올리는 것은 호환성을 깨는 변경이며 major 경계에서만 발생합니다.
상한(<9.0)은 다음 PHP major가 검증될 때까지 그것을 제외합니다. 새 PHP major에 대한 지원은 가정되는 것이 아니라 NextPDF 릴리스에서 추가됩니다.

문서 페이지는 또한 레시피가 검증된 PHP minor 버전의 compatibility 목록을 담고 있습니다. 레시피가 이식 가능한 경우 페이지가 더 오래된 minor(예: ["8.1", "8.2", "8.3", "8.4"])를 나열할 수 있는 반면, 엔진의 하드 설치 하한은 >=8.4로 유지됩니다. 의심스러울 때는 composer.json 제약이 페이지의 compatibility 힌트보다 우선합니다.

페이지의 수명 주기 프런트매터를 읽는 방법

페이지를 기반으로 무언가를 구축하기 전에 다음 여섯 필드를 사용해 평가하십시오.

필드	유형	읽는 방법
`stability`	`stable` \| `beta` \| `experimental` \| `deprecated`	페이지가 문서화하는 표면에 대한 호환성 약속입니다.
`since`	SemVer (예: `"3.1.0"`)	문서화된 표면을 도입한 버전입니다. 설치 버전이 최소한 이 버전 이상이어야 합니다.
`deprecated_since`	SemVer 또는 빈 값	설정되어 있으면 표면이 지원 중단된 것이며, 값은 그것을 지원 중단한 버전입니다. 빈 값은 지원 중단되지 않았음을 의미합니다.
`replaced_by`	사이트 경로 또는 빈 값	지원 중단 시 마이그레이션할 정규 후속 페이지입니다.
`version_lifecycle`	`active` \| `lts` \| `maintenance` \| `frozen` \| `eol`	문서화된 라인의 유지보수 등급입니다.
`eol_date`	ISO 날짜 또는 빈 값	`version_lifecycle`이 `eol`일 때의 수명 종료 날짜입니다. 그 외에는 빈 값입니다.

해석 예시: stability: stable, since: "3.0.0", deprecated_since: "", version_lifecycle: active를 가진 페이지는 3.0.0부터 존재해 온 프로덕션 준비 완료 표면을 문서화하며, 지원 중단되지 않았고, 활발히 유지보수되는 라인에 있습니다. ^ major 제약 아래에서 그것에 의존할 수 있습니다. stability: deprecated와 비어 있지 않은 replaced_by를 가진 페이지는 마이그레이션 신호입니다 — 후속 페이지를 읽고 다음 major 전에 이동을 계획하십시오.

적합성

이 정책은 버전 번호 부여에 대해 Semantic Versioning 2.0.0에, 변경 로그 생성에 대해 Conventional Commits 1.0.0에 적합합니다. PHP 지원 범위는 엔진 composer.json에 선언된 >=8.4 <9.0 제약입니다. 이 페이지는 자체적인 규범적 표준 주장을 하지 않습니다. 수명 주기 프런트매터 필드가 이미 인코딩하는 지원 계약을 문서화할 뿐입니다.

참고 자료

SPI 안정성 규칙 — 계약별 @stability 태그와 네 가지 하위 호환성 약속 등급(인터페이스, 열거형, 고정된 값 객체, 실험적).
CSS 지원 매트릭스 — HTML 및 CSS 렌더링 파이프라인에 대한, 진실성을 감사한 모듈별 지원 상태.
레퍼런스 색인 — API, 구성, 호환성 레퍼런스 자료의 진입점.