Changelog on kastori

버전 번호가 약속인 이유 — SemVer, Git Tag, CHANGELOG 관리

Wed, 10 Jun 2026 00:00:00 +0900

버전 번호는 사용자와의 약속이다

spring-boot-3.2.1을 쓰고 있다가 3.2.2로 올릴 때와 4.0.0으로 올릴 때 대응이 다르다. 3.2.2는 버그 수정이니 그냥 올려도 되지만, 4.0.0은 Breaking Change가 있을 수 있으니 마이그레이션 가이드를 먼저 읽어야 한다.

이 약속이 **Semantic Versioning(SemVer)**이다.

Semantic Versioning

형식: MAJOR.MINOR.PATCH — 예: 1.4.2

MAJOR → 하위 호환 안 되는 변경 (Breaking Change)
 API 응답 형식 변경, 파라미터 제거
 사용자가 코드를 수정해야 함
 예: 1.4.2 → 2.0.0

MINOR → 하위 호환되는 새 기능 추가
 기존 코드 수정 없이 새 기능 사용 가능
 예: 1.4.2 → 1.5.0

PATCH → 하위 호환되는 버그 수정
 예: 1.4.2 → 1.4.3

Conventional Commits와 연결

커밋 타입이 버전에 자동으로 영향을 준다.

feat: → MINOR 업 (1.4.2 → 1.5.0)
fix:, perf: → PATCH 업 (1.4.2 → 1.4.3)
docs:, style: 등 → 변화 없음
feat!: 또는
BREAKING CHANGE: → MAJOR 업 (1.4.2 → 2.0.0)

초기 개발 (0.x.x)

0.1.0 → 아직 안정적이지 않음. 언제든 Breaking Change 가능.
1.0.0 → 공개 API 확정. 이후부터 SemVer 약속 적용.

Git Tag — 버전 번호를 커밋에 붙이기

# 태그 생성 (annotated tag 권장)
git tag -a v1.2.0 -m "Release v1.2.0"

# 원격에 푸시 (태그는 git push에 포함 안 됨)
git push origin v1.2.0

# 모든 태그 한 번에 푸시
git push origin --tags

# 태그 목록 확인
git tag

# 특정 태그로 체크아웃
git checkout v1.2.0

lightweight vs annotated tag

lightweight tag: git tag v1.2.0
 → 단순 포인터. 커밋 해시에 별칭을 붙이는 것.

annotated tag: git tag -a v1.2.0 -m "메시지"
 → 태그 작성자, 날짜, 메시지, GPG 서명 포함
 → 릴리즈에는 annotated tag 권장

CHANGELOG — 릴리즈 이력 문서화

변경 이력을 사람이 읽을 수 있는 형태로 정리한 문서.

Keep a Changelog 형식

# CHANGELOG

## [Unreleased]

## [1.3.0] - 2026-06-04

### Added
- Google OAuth2 소셜 로그인 추가 (#123)
- 주문 취소 API 추가 (#124)

### Fixed
- 로그아웃 후 토큰 무효화 안 되는 버그 수정 (#125)

### Changed
- 회원 API 응답 형식 userId → id 변경

## [1.2.1] - 2026-05-20

### Fixed
- 주문 목록 페이징 오류 수정

자동 생성

Conventional Commits를 지켰다면 CHANGELOG를 자동으로 생성할 수 있다.

npm install -g conventional-changelog-cli
conventional-changelog -p angular -i CHANGELOG.md -s

릴리즈 프로세스 (GitHub Flow 기준)

# 1. 릴리즈할 main이 준비됐는지 확인
git checkout main && git pull

# 2. 버전 번호 결정 (커밋 내역 기반)
# feat 있으면 MINOR, fix만 있으면 PATCH

# 3. CHANGELOG 업데이트
conventional-changelog -p angular -i CHANGELOG.md -s
git add CHANGELOG.md
git commit -m "chore: v1.3.0 릴리즈 노트 업데이트"

# 4. 태그 생성 및 푸시
git tag -a v1.3.0 -m "Release v1.3.0"
git push origin main --tags

# 5. GitHub Release 생성 (UI 또는 gh CLI)
gh release create v1.3.0 --notes-from-tag

마치며

버전 관리는 “배포했다"를 기록하는 것이 아니라 “무엇이 어떻게 바뀌었는가"를 약속하는 것이다. SemVer + Conventional Commits + CHANGELOG 세 가지가 맞물리면 릴리즈마다 노트를 수동으로 작성할 필요도 없다.

다음 편에서는 rebase, squash, cherry-pick 같은 실무 고급 명령어를 다룬다.

커밋 메시지를 잘 쓴다는 것 — Conventional Commits 실전 가이드

Sat, 06 Jun 2026 00:00:00 +0900

git log에 남는 것들

git log --oneline

a3f21c9 수정
b12e8f1 fix
c94d3a2 asdf
d77f0e1 작업 완료
e23b1c7 ㅁㄴㅇ

6개월 전 내가 쓴 커밋들이다. 뭘 고쳤는지, 왜 고쳤는지 전혀 알 수 없다. 커밋 메시지는 코드의 히스토리이고, 미래의 나(또는 동료)에게 보내는 메모다.

Conventional Commits 형식

<type>(<scope>): <subject>

[optional body]

[optional footer]

# 실제 예시
feat(auth): Google OAuth2 소셜 로그인 추가

기존 이메일/비밀번호 로그인과 병행 사용 가능.
Google Cloud Console에서 OAuth 앱 등록 필요.

Closes #123

type 종류

type	언제 쓰나	버전 영향
`feat`	새 기능 추가	Minor ↑
`fix`	버그 수정	Patch ↑
`refactor`	리팩터링 (기능 변화 없음)	없음
`test`	테스트 추가/수정	없음
`docs`	문서 변경	없음
`style`	코드 포맷팅 (로직 무변화)	없음
`chore`	빌드, 패키지, CI 설정	없음
`perf`	성능 개선	Patch ↑

좋은 커밋 메시지의 조건

제목은 50자 이하, 명령형으로

# ✅ 좋음
feat(order): 주문 취소 API 추가
fix(auth): 로그아웃 후 토큰 무효화 안 되는 버그 수정

# ❌ 나쁨
feat(order): 주문 취소 기능을 구현했습니다 (과거형, 너무 김)
fixed bug (type 없음, 뭘 고쳤는지 모름)

body는 “왜"를 설명한다

refactor(payment): 결제 전략 패턴으로 분리

기존 PaymentService에 if/else로 결제 수단이 추가될 때마다
코드 수정이 필요했음. 전략 패턴 도입으로 OCP 달성.
새 결제 수단 추가 시 PaymentStrategy 구현체만 추가하면 됨.

what(무엇을 바꿨는가)은 코드 diff를 보면 안다. body에는 **why(왜 바꿨는가)**를 쓴다.

Breaking Change

하위 호환성이 깨지는 변경은 반드시 명시한다.

feat!: 사용자 API 응답 형식 변경

BREAKING CHANGE: userId 필드가 id로 변경됨.
기존 클라이언트는 필드명 수정 필요.

feat!의 !가 Breaking Change를 의미한다. SemVer에서 Major 버전 업 트리거.

커밋 단위 원칙

하나의 커밋 = 하나의 목적

# ✅ 좋음 — 목적이 명확한 단위
git commit -m "feat(user): 회원가입 엔티티 추가"
git commit -m "feat(user): 회원가입 서비스 로직 구현"
git commit -m "feat(user): 회원가입 API 엔드포인트 추가"
git commit -m "test(user): 회원가입 서비스 단위 테스트"

# ❌ 나쁨 — 여러 목적이 섞임
git commit -m "회원가입 기능 구현 및 버그 수정 및 테스트"

WIP 커밋 처리

작업 중간에 저장해야 할 때는 WIP 커밋을 만들고, PR 전에 정리한다.

# 작업 중 임시 저장
git commit -m "WIP: 결제 API 작업 중"

# PR 전에 squash로 깔끔하게 정리
git rebase -i HEAD~3
# WIP 커밋들을 squash해서 하나로 합치기

squash는 이 시리즈 마지막 편(고급 명령어)에서 다룬다.

CHANGELOG 자동 생성

Conventional Commits 형식을 지키면 CHANGELOG를 자동 생성할 수 있다.

# conventional-changelog 설치
npm install -g conventional-changelog-cli

# CHANGELOG.md 생성
conventional-changelog -p angular -i CHANGELOG.md -s

# CHANGELOG

## [1.3.0] - 2026-06-04

### Features
- **auth**: Google OAuth2 소셜 로그인 추가 (#123)
- **order**: 주문 취소 API 추가 (#124)

### Bug Fixes
- **auth**: 로그아웃 후 토큰 무효화 버그 수정 (#125)

커밋 메시지 하나하나가 릴리즈 노트가 된다. 다음 편에서는 이 커밋들을 담는 PR을 잘 쓰는 법을 다룬다.