[Spring Boot] 버전 체계 Semantic Versioning

Semantic Versioning(SemVer)은 소프트웨어 버전 관리를 위한 체계적인 규칙으로, MAJOR.MINOR.PATCH 형식으로 버전을 구성한다. 이 체계는 API나 라이브러리의 변경 사항을 명확히 전달하며, Spring Boot 프레임워크에서도 핵심 버전 관리 전략으로 채택되었다.

Basic syntax of semantic versioning

 

Semantic Versioning 기본 형식

MAJOR.MINOR.PATCH
MAJOR 버전(주 버전): 기존 기능과의 호환성을 깨뜨리는 변경 사항이 포함될 때 증가(예: 1.x.x → 2.0.0)
MINOR 버전(부 버전): 하위 호환성을 유지하면서 신기능이 추가될 때 증가(예: 2.1.x → 2.2.0)
PATCH 버전(패치 버전): 버그 수정 등 기능 변경 없이 내부 개선이 있을 때 증가(예: 2.2.0 → 2.2.1)

변경 유형	예시 버전 이동	영향도	업데이트 전략
PATCH 업데이트	3.4.0 → 3.4.1	낮음	즉시 적용, 테스트 후 적용
MINOR 업데이트	3.4 → 3.5	중간	테스트 후 적용
MAJOR 업데이트	2.7 → 3.0	높음	아키텍처 검토 필수

 

버전 

1. 주 버전 (MAJOR)

주 버전은 API 호환성이 깨지는 큰 변화가 있을 때 증가한다. 이는 기존 코드를 수정해야 하는 변경사항을 포함한다.

예시: WebSecurityConfigurerAdapter Deprecated

https://github.com/spring-projects/spring-security/issues/10822

Deprecate WebSecurityConfigurerAdapter · Issue #10822 · spring-projects/spring-security

 

위 issue를 보면 Spring Security 5.7.0-M2(2022년 2월 22일 배포)에서 WebSecurityConfigurerAdapter가 deprecated 처리되었다. 이후 주(MAJOR) 버전 6.0.0에서 해당 클래스는 완전히 제거되었다.

개발자는 deprecation 경고를 확인하고 주 버전 업데이트 이전 점진적으로 마이그레이션하며 대비할 수 있다.

 

여기서 Spring Security는 5.7에서 바로 6.0으로 넘어가지 않고, 버전 5.8을 제공했다.

Spring Boot 3.0 uses Spring Security 6.0. The Spring Security team have released Spring Security 5.8 to simplify upgrading to Spring Security 6.0.

이는 큰 변화를 점진적으로 도입하기 위한 버전 관리 방법이라 이해할 수 있다.

2. 부 버전 (MINOR)

부 버전은 하위 호환성을 유지하면서 새로운 기능을 추가할 때 증가한다. 기존 코드는 수정 없이 계속 동작한다.

예시: Spring Boot Version 3.3.x → 3.4.0

Spring Boot 3.4.0 릴리스 노트를 통해 어떤 사항들이 변경 되었는지 살펴보자.

https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.4-Release-Notes

Spring Boot 3.4.0에서는 새로운 기능들이 추가되었는데, MockMvcTester라는 새로운 테스트 도구가 도입되었고, 여러 서드파티 라이브러리의 최신 안정 버전으로 업그레이드되었다고 한다. 이러한 변경은 새로운 기능을 제공하지만, 기존의 코드를 깨뜨리지 않으므로 MINOR 버전이 증가한다고 이해할 수 있다.

또한 문서에서 "Deprecations from Spring Boot 3.2" 섹션을 보면:

"Classes, methods, and properties that were deprecated in Spring Boot 3.2 and marked for removal in 3.4 have been removed in this release."

3.2에서 deprecated 되고 "3.4에서 제거될 것"이라고 명시적으로 표시된 기능들이 3.4(부버전 업데이트)에서 실제로 제거되었음을 알려주고 있다.

 

이를 통해 일반적으로 명시적인 제거 시점이 표시되지 않은 deprecated 기능은 보통 다음 주버전에서 제거되지만, "X.Y 버전에서 제거 예정"으로 명확히 표시된 경우 해당 부버전에서도 제거될 수 있다는 점을 알 수 있다.

 

 

 

https://joaovieira.ca/spring-boot-3-3-1-jackson-jdk8module/

How upgrading from Spring Boot 3.2.5 to 3.3.1 broke our object mapper

위 링크의 글에서 작성자는 Spring Boot 3.2.5에서 3.3.1로의 업그레이드가 MINOR 버전 업그레이드(3.2→3.3)이므로 호환성을 깨는 변화가 없어야 한다고 생각했다고 한다. 하지만 실제로는 Jackson Databind 라이브러리가 2.15.4에서 2.17.1로 업데이트되면서 Optional 타입의 직렬화 방식이 변경되어 호환성 문제가 발생했다. 

위 사례를 보았을때, MINOR 버전 업그레이드도 종속 라이브러리의 변경을 포함할 수 있고, 종속 라이브러리의 변경이 호환성 문제를 일으킬 수도 있기 때문에 부(MINOR) 버전 또한 업그레이드 시 변경 내역(changelog)을 확인하는 것이 중요할 것 같다.

 

 

3. 패치 버전 (PATCH)

패치 버전은 버그 수정, 보안 패치, 성능 최적화와 같은 하위 호환성을 유지하는 수정사항에 사용한다.

예시: 3.4.0 → 3.4.1 

Spring Boot 3.4.1 patch 버전 업데이트 노트를 통해 어떤 사항들이 변경 되었는지 살펴보자.

https://github.com/spring-projects/spring-boot/releases/tag/v3.4.1

Release v3.4.1 · spring-projects/spring-boot

3.1. 버그 수정

 

이러한 수정은 기존 기능을 올바르게 작동하도록 하는 것이지, 새로운 기능을 추가하는 것이 아니다.

3.2 문서 개선

문서 수정은 API나 기능 변경 없이 사용자 이해도를 높인다.

3.3 의존성 업그레이드

패치 버전에서의 의존성 업그레이드는 주로 동일한 major,minor 버전 내에서의 패치 업데이트다. 이는 하위 호환성을 보장하면서 보안 취약점 및 버그를 수정한다.

패치 버전 업데이트를 통해 버그 수정, 문서 개선, 의존선 업그레이드 등을 안전하게 해결할 수 있기 때문에 보안 취약점 등의 중요 개선 사항이 존재한다면 확인 후 최신 패치 버전을 적용하는 것이 권장된다.

 

 

참고 자료

• Semantic Versioning 공식 웹사이트
• Spring Boot 버전 관리 가이드
• npm Semantic Versioning 문서

Semantic Versioning 2.0.0

 

Spring Boot

 

About semantic versioning | npm Docs

https://techblog.lycorp.co.jp/ko/how-to-migrate-to-spring-boot-3

실전! Spring Boot 3 마이그레이션