오픈소스 릴리즈 체크리스트 — npm·PyPI·GitHub 배포 전 놓치면 후회하는 38개 항목

소스코드가 실제로 동작하는지, 테스트가 통과하는지 확인하는 단계다. 코드 품질 게이트가 무너지면 이후 패키징·보안 작업이 모두 무의미해진다. 배포 직전에 테스트를 처음 돌리는 것이 아니라, CI에서 항상 돌아가는 구조를 먼저 갖추는 것이 핵심이다.

패키지 메타데이터가 잘못되면 npm/PyPI 검색에서 누락되거나, 라이선스 분쟁이 생기거나, 설치 명령어가 README와 다른 상황이 발생한다. npm pack --dry-run으로 생성되는 파일 목록을 반드시 눈으로 확인하는 습관이 필요하다.

npm의 경우 npm pack으로 생성된 .tgz 파일을 직접 확인하는 것이 가장 확실하다. tar -tzf package-name-1.0.0.tgz 명령으로 포함된 파일 목록을 출력해보면 된다. .env 파일이나 빌드 캐시가 포함되는 경우가 생각보다 많다. PyPI라면 twine check dist/*로 배포 전 메타데이터 검증이 가능하다.

공급망 보안(supply chain security) 이슈는 오픈소스에서 가장 빠르게 신뢰를 잃는 경로다. node_modules나 requirements.txt에 취약한 버전이 포함된 채로 배포되면 해당 패키지를 설치한 모든 사용자에게 위험이 전파된다. 특히 git 히스토리에 secrets가 남아있는 경우 패키지 배포와 무관하게 이미 노출된 상태다.

코드는 완벽한데 README가 없으면 아무도 쓰지 않는다. 반대로 문서만 좋고 코드가 불안정하면 이슈가 쏟아진다. 문서화는 사용자가 패키지를 신뢰하는 첫 번째 기준이다. 특히 Quick Start 예제가 실제로 동작하는지 직접 복사해서 실행해보는 습관이 중요하다.

CHANGELOG는 Keep a Changelog 형식을 기준으로 작성하면 일관성을 유지하기 쉽다. Added, Changed, Deprecated, Removed, Fixed, Security 섹션으로 분류하면 사용자가 영향 범위를 빠르게 파악할 수 있다. conventional-changelog나 git-cliff 같은 도구로 git 커밋 메시지를 기반으로 자동 생성하는 방법도 있다.

수동 배포는 실수를 유발한다. git tag를 푸시하면 자동으로 테스트→빌드→배포가 이뤄지는 파이프라인을 구성해두면 재현 가능한 릴리즈가 가능하다. GitHub Actions를 기준으로 점검 항목을 정리했다. CI 파이프라인에 배포 자동화를 추가하기 전에 dry-run으로 먼저 검증하는 것이 원칙이다.

Semantic Versioning(SemVer)은 MAJOR.MINOR.PATCH 구조다. 오픈소스에서 버전을 잘못 올리면 사용자 앱이 갑자기 깨지거나, breaking change를 패치로 배포해 신뢰를 잃는다. 특히 0.x.y 버전에서 1.0.0으로 전환하는 시점을 놓치는 경우가 많다.

0.x.y 버전은 MAJOR 변경 없이도 언제든 breaking change가 가능한 불안정 단계로 간주된다. 실제 사용자가 생기기 시작했다면 1.0.0으로 올리고 SemVer를 엄격하게 적용하는 것이 맞다. np, release-it 같은 도구를 쓰면 버전 번호 업데이트 → git tag → npm publish 과정을 한 번에 처리할 수 있다.

배포 후 5~10분 내에 실제로 설치해보는 것이 가장 중요한 검증이다. npm 미러 반영 지연이나 PyPI 인덱싱 오류로 설치가 안 되는 경우가 종종 있다. 배포 직후 빈 환경에서 설치 테스트를 자동화해두는 것이 이상적이다.