[Rust 공식문서 한국어 정리] ㉙. Rust 크레이트 배포 가이드

[Rust 공식문서 한국어 정리] ㉙. Rust 크레이트 배포 가이드

원문 제목: Publishing on crates.io — Cargo Reference
작성자: Rust Cargo Team

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

이 문서는 Rust 크레이트를 crates.io에 배포하는 절차와 모범 사례를 설명합니다.
Cargo.toml 설정, API 문서화, 버전 관리, 그리고 배포 후 관리까지 전 과정을 다룹니다.
오픈소스 라이브러리를 처음 공개하는 개발자가 놓치기 쉬운 라이선스, 문서, 의존성 관리 포인트를 짚어줍니다.
crates.io 생태계의 품질을 유지하고, 사용자가 크레이트를 신뢰할 수 있도록 하는 방법을 중심으로 설명합니다.
Rust 패키지를 공개하거나 낭부 프라이빗 레지스트리를 운영하려는 개발자에게 필수적입니다.

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

① crates.io: Rust의 공식 패키지 레지스트리이자, Cargo의 기본 다운로드 소스입니다.
② Cargo.toml Metadata: 이름, 버전, 작성자, 라이선스, 설명, 키워드 등의 필수 메타데이터입니다.
③ Documentation: cargo doc으로 생성된 API 문서는 docs.rs에서 자동으로 호스팅됩니다.
④ yank: 배포된 버전을 삭제하지 않고 설치를 막는 기능으로, 보안 이슈 대응에 사용됩니다.

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

crates.io에 배포하려면 먼저 API 토큰을 발급받아 cargo login에 등록해야 합니다.
Cargo.toml의 [package] 섹션에는 name, version, edition, authors, license, description, repository 등이 포함되어야 합니다.
라이선스는 SPDX 표현식으로 명시하고, README.md는 repository의 얼굴이 되므로 충실히 작성합니다.

API 문서화는 배포 전 필수 점검 항목입니다.
/// 문서 주석과 //! 모듈 문서를 작성하고, cargo doc --open으로 로컬에서 미리 확인합니다.
배포 후 docs.rs가 자동으로 문서를 빌드하고 호스팅하며, 모든 공개 API에 문서가 있는지 검사합니다.

배포 명령은 cargo publish입니다.
이 명령은 프로젝트를 압축하고, 의존성을 포함한 메타데이터를 crates.io에 업로드합니다.
업로드된 버전은 영구히 남으며 삭제할 수 없으므로, 배포 전 cargo publish --dry-run으로 시뮬레이션합니다.

yank는 배포된 버전을 사용 불가로 표시하는 기능입니다.
cargo yank --vers x.y.z로 해당 버전을 yank하면, 새로운 의존성 해석에서는 선택되지 않습니다.
이미 lock 파일에 고정된 프로젝트는 계속 사용할 수 있으므로, 기존 빌드를 깨뜨리지 않으면서 보안 패치를 유도할 수 있습니다.

버전 관리는 SemVer를 엄격히 준수해야 합니다.
API 변경 여부를 cargo-semver-checks로 자동 검증하고, CHANGELOG.md에 변경 내역을 기록합니다.
cargo-release와 같은 도구를 사용하면 버전 범프, 태그 생성, 배포를 하나의 명령으로 자동화할 수 있습니다.

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

배포 전 CI에서 cargo test, cargo clippy, cargo fmt --check를 통과시킵니다.
cargo publish --dry-run으로 패키지가 올바르게 구성되었는지 확인한 뒤 실제 배포합니다.
보안 취약점이 발견되면 즉시 yank하고, PATCH 버전을 올려 수정판을 배포합니다.

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

crates.io 배포는 Rust 생태계에 기여하는 중요한 단계입니다.
메타데이터, 문서, SemVer 준수를 철저히 하면 사용자 신뢰를 얻고 유지보수가 용이해집니다.
yank와 PATCH 배포를 통해 보안 이슈에도 신속하고 안전하게 대응할 수 있습니다.

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

원문: https://doc.rust-lang.org/cargo/reference/publishing.html
crates.io: https://crates.io/

#Rust #CratesIO #Publishing #Cargo #SemVer #OpenSource #번역