유의적 버전(Semantic Version) 형식
- 주 버전 (Major Version): 이전 버전과 호환되지 API 변화
- 부 버전 (Minor Version): 이전 버전과 호환되면서 새로운 기능을 추가
- 수 버전 (Patch Version): 이전 버전과 호환되면서 버그를 수정한 것
- 사전 배포 (Pre-release): 시험판 및 빌드 메타데이터에 관한 레이블
호환성
만약 공개(Public) API를 사용하고 있다면, 주(Major) 버전을 올리는 것은 신중해야한다.
주 버전이 달라지면, 하위 버전에 대해 호환성을 유지해야하는 의무가 없어진다.
그러나, 부(Minor) 버전 다르다. 부 버전이 업그레이드 될 때는 하위 버전의 모든 내용을 포함하고 있아야한다.
이전 버전에서 영 좋지 않은 함수가 있더라도, 부 버전을 업그레이드 할 때는 기능을 삭제하는 것이 아니라 deprecated 시켜야 한다.
공개 API를 사용하는 유저가 해당 영 좋지 않은 함수를 차기 부 버전에서 호출하더라도 정상적으로 동작해야한다. 다만, 해당 함수를 사용하지 말라는 경고(Warning)을 콘솔등에 띄어주는게 좋다. 여기서 포인트는 ‘경고(Warning)’이지 ‘에러(Error)’가 아니다.
만약 치명적인 결함이 존재한다면, 세가지 중에 하나를 고를 수 있는데,
- 주 버전을 올리고 해당 기능을 삭제한다.
- 원칙을 무시하고 부 버전을 올린 뒤 해당 기능을 삭제한다.
- 경고를 아주 요란하게 띄우고 사용에 대한 책임은 유저에게 넘긴다.
사실 위 3가지 모두 정말 골치 아픈 경우다. 해당 기능 하나 때문에 주 버전을 올리긴 좀 그렇고, 그렇다고 원칙을 무시하자니 찜찜하고, 세번째는 양심에 걸린다. 가장 좋은 방법은 영 좋지 않는 함수를 만들지 않는 것. 하지만 그게 말처럼 쉬울까.
의외로 3번째 방법이 가장 흔하게 사용될 수 있다. 왜냐하면 라이센스 때문이다. 우리가 아무 생각 없이 이용하는 MIT LICENSE를 보자. MIT LICENSE에는 ‘보증(Warranty)’과 ‘책임(Liability)’이 없다.
(권장하지 않음) 이 방법이 싫다면 원칙을 무시해보자. 유의적 버전 머리말에도 명세에 너무 매몰되지 말라고 한다. 다만, 부 버전 업데이트에서 API를 삭제할 생각이라면, 시스템에 악영향을 주거나 심각한 보안 문제 같은 경우에만 하자. API를 삭제한다는 것은 공개 API 사용자들에겐 충공깽 그 자체의 행동이다.
유의적 버전 명세 요약
- 형식 X.Y.Z를 지킨다. (각각 자연수, 앞에 0이 붙으면 안됨)
- 배포시 변경 금지 (일명 잠수함 패치)
- 0.y.z = 초기 개발용 (0.1.0 부터 시작)
- 1.0.0 = 정식 릴리즈
- 부 버전, 수 버전을 올릴 때는 호환성 여부를 반드시 체크
- 부 버전이 올라가면 수 버전 0으로 초기화, 주 버전이 올라가면 부, 수 버전 0으로 초기화
Pre-release Lable
x.y.z 다음에 ‘-‘, ‘.’, ‘+’ 등을 붙여 lable을 표시할 수 있다.
이 파트는 필수가 아니다.
- 버전에 대해 명확하게 설명 하고 싶을 때
- 소프트웨어 릴리즈 라이프 사이클 (Software Release Life Cycle)을 도입하고 싶을 때
사용하면 된다.
또, 일반적으로 통용되는 용어만 존재할 뿐 해석은 전적으로 API 설계자에게 있다.
- pre-alpha: 테스트 이전 단계
- alpha: 주로 내부적으로 테스트할 때 사용. 매우 불안정함.
- beta: 주로 공개적으로 많은 사람들에게 테스트할 때 사용. 정식버전보다 불안정함.
- rc(릴리즈 후보): 치명적인 버그가 발견되지 않으면 출시할 준비가 되었음.
- release: 검증 / 테스트를 모두 통과한 마지막 rc. stable 버전과 LTS(Long-term Support)로 나뉨.
순서와 표기법은 여기서 확인하자.
CHANGELOG
버전 업그레이드시 변경 사항에 대해 꼼꼼하게 기록해줘야한다. 다음은 Node.js의 변경사항 기록이다.