07 시맨틱 버저닝 - woowacourse-teams/2026-jachwi-sunbae GitHub Wiki
개요
"일단 이전 버전으로 돌리자!" 여러 기능을 한꺼번에 개발하고 테스트한 뒤 배포했는데, 배포 직후 어디선가 에러가 발생했다. '그럼 그냥 예전 버전으로 되돌리면 되지'라고 했지만... 어느 시점의 코드가 문제 없던 버전인지 확실하지 않다. 기능 개발이 한 브랜치에서 섞여 있었고, 이전에 어떤 변경이 있었는지도 정리가 안 돼 있어서 되돌리는 것도, 고치는 것도 어렵다.
완료 조건
- 릴리스할 때마다 프론트엔드 리소스에 시맨틱 버저닝(Semantic Versioning) 규칙에 따라 버전을 명시한다.
- 각 버전마다 어떤 변경이 있었는지 changelog 등을 통해 명확하게 확인할 수 있다.
- 문제가 발생했을 때, 이전 안정적인 버전으로 되돌아갈 수 있는 기준이 존재한다.
- 팀원 모두가 현재 배포된 버전과 변경 내역을 쉽게 확인할 수 있다.
기술 역량 목표
- 시맨틱 버저닝(Semantic Versioning)의 규칙(Major, Minor, Patch)을 이해하고, 릴리스 버전에 적용할 수 있다.
- Git에서 특정 버전을 명시하고, 필요한 시점으로 되돌릴 수 있다.
- 버전별 변경 내역을 기록하는 changelog를 작성하고 관리할 수 있다.
- 현재 배포된 버전 정보를 명확하게 추적할 수 있다.
버전
버전 증가 기준
| 구분 | 적용 기준 | 예시 |
|---|---|---|
| MAJOR | 기존 API 데이터와 호환되지 않는 변경 | 기존 프론트엔드가 사용할 수 없는 API 계약 변경 |
| MINOR | 기존 기능과 호환되는 새로운 기능 추가 | 새로운 동네 탐색 기능 추가 |
| PATCH | 기존 기능과 호환되는 오류 수정,성능,개선,내부 리팩터링 | 지도 마커 위치 오류 수정 |
버전 관리
| 파일 | 관리하는 값 |
|---|---|
| VERSION | 제품 버전 |
| frontend/package.json | version |
| frontend/package-lock.json | 프로젝트 버전 |
| frontend/public/version.json | 배포 버전 확인용 값 |
릴리즈할 떄 위의 파일의 버전을 맞춥니다.
실제 배포된 버전 확인
프론트엔드와 백엔드가 같은 제품 버전을 사용하더라도, 배포 시점이나 성공 여부는 다를 수 있습니다.
{
"version": "1.1.0"
}
그래서 /version.json 의 배포 버전을 확인해야합니다.
릴리스 전 검증과 태그 생성
릴리스 전에 저장소 루트에서 다음 검사를 실행합니다.
python3 .github/scripts/check_versions.py
python3 .github/scripts/check_changelog.py "$(tr -d '[:space:]' < VERSION)"
버전 검사는 제품 버전의 형식과 각 설정 파일의 버전 일치를 확인합니다. 변경 내역 검사는 해당 버전의 CHANGELOG 항목을 확인합니다. 프론트엔드 CI에서도 두 검사를 실행합니다.
main에 변경이 병합되면 Release 워크플로는 다음 작업을 수행합니다.
1. 버전과 CHANGELOG를 검증합니다.
2. 릴리스 커밋에 vMAJOR.MINOR.PATCH 형식의 Git 태그를 생성합니다.
3. 해당 버전의 변경 내역으로 GitHub Release를 생성합니다.
이미 같은 이름의 태그가 다른 커밋을 가리키면 작업을 실패시킵니다. 같은 버전이 서로 다른 코드를 의미하지 않도록 하기 위한 검사입니다.