패키지 의존성 고정과 버전 릴리스 워크플로 정착

버전 릴리스 커밋이다. 0.9.3으로 버전을 올리고 의존성을 고정한 작업인데, 이걸 단순한 버전 번호 변경이라고만 보면 놓치는 부분이 꽤 많다.

왜 0.9.3인가: 버전 관리의 의사결정

가장 먼저 고민할 지점은 버전 번호 선택이다. 패치 릴리스(patch: 0.9.3)를 하는 것이 맞는가, 아니면 마이너(minor: 0.10.0) 또는 메이저(major: 1.0.0)를 해야 하는가 하는 문제다.

팀에서 정한 Semantic Versioning 규칙이 있다면:
- 메이저: 호환되지 않는 API 변경
- 마이너: 기능 추가 (역호환성 유지)
- 패치: 버그 수정, 핫픽스

0.9.3이라는 것은 "현재 개발 중인 프로덕션 전 단계에서 패치 수준의 개선/수정을 했다"는 신호다. 이걸 판단하는 과정이 의외로 중요한데, 개발 초기 단계(0.x 버전)인 상태에서 메이저 버전을 올리는 것은 신중해야 하기 때문이다. 한 번 1.0을 선언하면 API 안정성에 대한 약속이 생기니까.

package.json과 package-lock.json: 의존성의 투명성

이 두 파일의 변경이 중요한 이유를 다시 한번 생각해봤다.

package.json은 선언이고, package-lock.json은 다짐이다.

릴리스 커밋에서 package-lock.json이 함께 변경되는 것은:
- 프로덕션 배포를 위한 의존성 재검증 → 혹시 모를 버전 불일치 해결
- 팀 전체가 동일한 환경에서 작업하도록 강제 (CI/CD 포함)
- 배포 재현성 → 6개월 뒤 다시 빌드해도 같은 의존성으로

이전에 봤던 사례 중에, 누군가 package.json만 커밋하고 lock 파일을 빼먹어서, 개발 환경과 배포 환경의 의존성이 살짝 달라 프로덕션에서만 버그가 나던 일이 있었다. 그래서 이제는 버전 릴리스마다 lock 파일도 꼭 함께 커밋하는 것을 팀 기준으로 삼았다.

릴리스 워크플로우: 한 줄 커밋 뒤의 프로세스

실제로는 이 커밋 한 줄이 나오기까지 생각할 게 많다:

• 테스트 통과 → 릴리스 브랜치로 병합 가능?
• CHANGELOG 갱신 → 0.9.3에서 뭐가 바뀌었는지 기록
• 버전 번호 일치성 → package.json, package-lock.json 외에도 타 설정 파일 확인
• 배포 리드타임 → 언제 실제 프로덕션 배포할 것?

이 커밋 자체는 "버전을 올렸다"는 신호일 뿐이고, 실제 배포(publish to npm, 또는 내부 registry)는 별개의 단계다. 팀에서 릴리스와 배포를 엄격히 분리하는 이유도 여기 있다. 버전 태그를 먼저 긋고, 팀 리뷰 후 배포하는 식으로.

어떤 팀은 릴리스 커밋을 자동화하기도 한다:

npm version patch  # 버전 올리고 자동 커밋/태그
git push origin --follow-tags  # 푸시

하지만 우리는 수동 검토 단계를 선호한다. 패치 하나여도 누군가는 "이 버전에 정말 그 수정사항이 포함됐나?" 확인하고, CHANGELOG가 정확한지 검증하는 과정을 거친다.

한 발 물러나서: 메타 버전 관리

릴리스 커밋을 하면서 배운 점 중 하나는, 버전 관리 자체도 기술 부채가 될 수 있다는 것이다.

초기에는 "버전 올려야 할 때 올리자" 하다가, 나중에 보니:
- 버전 규칙이 일관되지 않음 (0.1.5 다음에 왜 0.3.0?)
- CHANGELOG가 없거나 불완전
- 배포와 버전 관리의 경계가 불명확

그래서 지금은 명확한 기준을 문서화해뒀다. 팀에 새로 들어온 사람도 "0.9.3을 하려면 이 체크리스트를 따르면 된다"고 말해줄 수 있게.

이런 작은 커밋이 쌓이면서, 결국 팀의 릴리스 문화가 만들어진다. "chore(release)"라는 prefix도 그 일부—이건 기능이 아니라 운영 작업임을 명시하는 신호다.

🛒 이 글과 어울리는 추천 상품

• 외장SSD 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.