[Rust 공식문서 한국어 정리] ㉘. Rust SemVer 가이드

[Rust 공식문서 한국어 정리] ㉘. Rust SemVer 가이드

원문 제목: SemVer Compatibility — Cargo Reference
작성자: Rust Cargo Team

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 1. 서론 — 이 문서가 다루는 내용
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

이 문서는 Rust 크레이트 버전 관리를 위한 SemVer(Semantic Versioning) 규칙을 상세히 설명합니다.
MAJOR.MINOR.PATCH 형태의 버전 번호가 각각 어떤 의미를 갖고, Rust 생태계에서 어떻게 적용되는지를 다룹니다.
API 호환성과 바이너리 호환성의 차이, 타입 시스템 관점에서의 주요/부minor/패치 변경 판단 기준을 제시합니다.
Cargo의 의존성 해석 방식과 SemVer의 관계를 이해하면 의도치 않은 빌드 실패를 방지할 수 있습니다.
라이브러리 개발자와 의존성을 관리하는 애플리케이션 개발자 모두에게 필수적인 지침서입니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔑 2. 핵심 개념 4가지
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

① MAJOR: 하위 호환성이 깨지는 API 변경 시 증가합니다.
② MINOR: 하위 호환성을 유지하는 기능 추가 시 증가합니다.
③ PATCH: 하위 호환성을 유지하는 버그 수정 시 증가합니다.
④ API vs Binary Compatibility: Rust에서는 소스 호환성과 바이너리 호환성이 구분될 수 있습니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📖 3. 주요 내용 상세
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Rust의 SemVer 해석은 언어의 타입 시스템과 밀접하게 연관되어 있습니다.
새로운 공개 타입, 트레이트, 함수를 추가하는 것은 MINOR 변경입니다.
그러나 기존 함수의 시그니처를 변경하거나, 공개 타입의 필드를 제거하면 MAJOR 변경이 됩니다.

Cargo는 기본적으로 SemVer 호환 버전 범위 내에서 최신 버전을 선택합니다.
^1.2.3 의존성은 >=1.2.3, <2.0.0을 의미하며, MINOR와 PATCH 업데이트를 자동으로 허용합니다.
따라서 MINOR 변경에서도 기존 코드가 컴파일되지 않을 수 있는 상황(예: 타입 추론 모호성)이 발생할 수 있습니다.

바이너리 호환성(ABI)은 소스 호환성과 다릅니다.
Rust는 현재 안정적인 ABI를 보장하지 않으므로, 동일한 MAJOR 버전 내에서도 재컴파일이 필요합니다.
그러나 소스 수준에서의 호환성은 Cargo와 의존성 해석의 핵심이며, SemVer는 소스 호환성을 기준으로 합니다.

주의해야 할 MINOR 변경의 예시들이 있습니다.
기존 구조체에 새 필드를 추가하면, 구조체 리터럴 문법이 깨질 수 있습니다.
비공개 필드가 있는 구조체에는 #[non_exhaustive]를 붙여 이러한 문제를 예방할 수 있습니다.
기본 구현이 있는 트레이트에 새 메서드를 추가하면, 이를 수동 구현한 타입들이 컴파일 오류를 겪을 수 있습니다.

자동 트레이트(Send, Sync, Unpin 등)의 자동 구현 변경은 특히 민감합니다.
타입의 낭부 필드 구성이 바뀌어 자동 트레이트 구현이 추가되거나 제거되면, 이는 SemVer 관점에서 중요한 변경일 수 있습니다.
라이브러리 개발자는 이러한 영향을 문서에 명시하고, 가능한 한 #[non_exhaustive]와 semver trick을 활용해야 합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛠 4. 실전 활용
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

라이브러리를 배포하기 전 cargo-semver-checks로 API 변경 사항을 자동 분석합니다.
신규 기능 추가 시 MINOR를, 버그 수정 시 PATCH를, API 변경 시 MAJOR를 엄격히 구분하여 버전을 올립니다.
#[non_exhaustive]를 공개 구조체와 열거형에 적용하여 미래 확장성을 보장합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 5. 정리
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SemVer는 Rust 생태계의 의존성 관리를 원활하게 하는 근간입니다.
API 호환성 기준을 명확히 이해하고, Cargo의 버전 해석 방식을 숙지하면 예상치 못한 빌드 실패를 줄일 수 있습니다.
라이브러리 개발자는 SemVer의 세부 규칙을 준수하며 사용자의 신뢰를 유지해야 합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔗 출처 링크
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

원문: https://doc.rust-lang.org/cargo/reference/semver.html
cargo-semver-checks: https://github.com/obi1kenobi/cargo-semver-checks

#Rust #SemVer #Versioning #Cargo #Compatibility #번역