패키지 버전 릴리즈에 담긴 팀의 배포 원칙

0.9.4 버전으로 릴리즈를 준비했다. 언뜻 package.json과 package-lock.json 두 파일의 버전 번호만 올리는 작은 작업처럼 보이지만, 이 과정에서 팀 차원의 여러 고민과 원칙이 담겨 있다.

버전 범핑의 신호

chore(release) 커밋은 "이 변경은 기능이나 버그 수정이 아니라 운영 작업"이라는 신호다. 우리 팀에서는 Semantic Versioning을 따르는데, 0.9.4는 0.9.3 대비 마이너 범위의 변경을 의미한다. 실무에서는 이 버전 범핑 타이밍을 어떻게 결정할지가 중요한데, 보통 다음과 같은 기준을 본다:

• 새로운 기능이나 개선사항이 충분히 쌓였을 때
• 버그 수정들을 하나의 단위로 묶어 배포할 때
• 외부 의존성 업그레이드가 주요 변경을 포함할 때

이번 0.9.4는 이런 릴리즈 주기 중 하나가 도래했다는 뜻이고, 그것이 코드화된 순간이다.

두 파일의 역할과 일관성

이 커밋에서 변경되는 package.json과 package-lock.json은 서로 다른 책임을 가진다.

두 파일을 함께 커밋하는 이유는 일관성이다. 팀원이 checkout 했을 때 정확히 같은 버전의 의존성이 설치되어야 하고, 릴리즈 버전도 모두에게 동일하게 적용되어야 한다. 만약 package.json만 커밋하고 package-lock.json을 빠뜨렸다면, 누군가의 환경에서는 다른 의존성 버전이 설치될 수 있고, 그것은 "분명히 내 환경에서는 됐는데"라는 팀 내 마찰의 원인이 된다.

릴리즈 프로세스와 신뢰

버전 범핑 커밋 자체는 간단하지만, 이것이 필요한 배경에는 릴리즈 프로세스가 있다.

1. 기능/버그 수정 작업 완료
   ↓
2. 테스트 및 검증
   ↓
3. CHANGELOG 업데이트 (선택)
   ↓
4. package.json 버전 범핑
   ↓
5. npm run build / tag 생성
   ↓
6. 배포

chore(release) 커밋이 히스토리에 명시적으로 남는 것의 가치는, 언제 어떤 버전이 배포되었는지를 자명하게 만드는 것이다. 6개월 뒤 "이 기능은 언제부터 들어갔지?"라는 질문이 생겼을 때, 커밋 로그를 보면 0.9.4 태그와 함께 그 맥락을 찾을 수 있다.

마주한 선택지와 회고

팀을 이끌다 보면 "버전을 언제 올릴 것인가"라는 정책 결정도 필요하다. 어떤 팀은 자동화로 버전을 관리하고(semantic-release 같은 도구), 어떤 팀은 수동으로 결정한다. 우리는 지금 수동 결정 모델을 택했고, 이는 릴리즈에 앞서 "정말 지금이 릴리즈 타이밍인가"를 한 번 더 생각하게 만든다.

이 방식의 장점은 신중함이고, 단점은 관리 오버헤드다. 향후 배포 속도가 중요해지면 자동화로 전환할 수도 있다. 지금은 이 균형이 우리 팀 규모와 배포 주기에 맞다고 판단했다.

작은 커밋 하나, 하지만 거기에 담긴 의사결정과 팀의 신뢰 구조가 있다는 걸 자주 생각하게 된다.

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

• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →

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