프로그램 버전 관리 지침(소프트웨어 개발 가이드)

프로그램 개발에서 가장 중요한 것 중에 하나가 버전 관리입니다.

버전 관리가 되지 않으면, 복잡하고 긴시간 작업해야 하는 프로젝트에서 문제가 발생 했을 때 대처하기가 어렵습니다.

심각한 경우에는 처음부터 다시 해야 하는 일도 발생 할 수 있습니다.

아주 끔찍한 일이지만, 미비한 경험의 초창기에 클러스터 시스템 운영 프로그램을 개발하면서, 이런 일들을 직접 겪어보기도 했습니다.

클러스터 시스템

그래서, 소프트웨어 개발 지침을 정의하고, 지키는 것은 개발자에게 매우 중요한 일입니다.

 

---

 

프로그램 버전 관리 지침 v1.1

1. 목적
본 지침은 소프트웨어 개발 및 배포 과정에서 버전을 체계적으로 관리하고, 개발자·운영자·사용자가 모두 일관된 기준으로 버전을 이해하고 활용할 수 있도록 하는 것을 목적으로 한다.

2. 버전 관리 체계

2.1 Semantic Versioning (SemVer) 체계
SemVer(Semantic Versioning, 의미적 버전 관리)는 소프트웨어 버전을 MAJOR.MINOR.PATCH 형식으로 관리하는 국제적으로 널리 쓰이는 규칙이다.

기본 구조
MAJOR.MINOR.PATCH
• MAJOR (주 버전): 하위 호환성이 깨지는 큰 변경 발생 시 증가. (예: API 구조 변경, 기존 기능 제거)
• MINOR (부 버전): 하위 호환성을 유지하며 기능이 추가될 때 증가. (예: 새로운 기능, 옵션 추가)
• PATCH (수정 버전): 버그 수정, 보안 패치, 성능 개선 등 작은 변경 시 증가.

예시
• 1.0.0 → 최초 안정화 릴리즈
• 1.1.0 → 새로운 기능 추가
• 1.1.1 → 버그 수정
• 2.0.0 → 하위 호환성 깨뜨리는 큰 변경

확장 규칙

• 프리릴리즈(Pre-release): -alpha, -beta, -rc 등 접미사로 구분.

예: 1.0.0-alpha, 1.0.0-beta.2, 1.0.0-rc.1

• 빌드 메타데이터(Build metadata): 빌드 환경, 날짜, 해시 값 등 부가 정보.

예: 1.0.0+20251002, 1.0.0+exp.sha.5114f85

2.2 빌드 번호 (Build Number)
• 정의: 빌드 또는 배포 단위마다 생성되는 고유 식별자.
• 형식: Major.Minor.Patch.Build 또는 Major.Minor.Patch (Build ####).

• 관리 원칙:
1. CI/CD 환경에서 자동 증가.
2. 같은 소스라도 빌드 환경/날짜에 따라 별도 번호 부여.
3. 디버깅 및 이슈 추적 시 빌드번호를 반드시 활용.

플랫폼별 활용
• Windows: 파일 버전에 1.2.3.45 형태로 표시.
• iOS: CFBundleVersion을 빌드번호로 관리.
• Android: versionCode를 빌드번호로 사용.

3. 브랜치 전략과 버전 관리
• main/master: 안정화된 정식 릴리즈 버전.
• develop: 차기 릴리즈 준비.
• feature/*: 기능 개발용, 버전 증가 없음.
• release/*: 릴리즈 준비 단계, Minor/patch 버전 반영.
• hotfix/*: 긴급 수정, Patch 버전 증가.
모든 릴리즈 시 Git 태그(Tag)를 통해 버전을 명확히 기록한다.

4. 배포 정책

4.1 버전 구분
• 정식 릴리즈: 안정화된 버전만 배포.
• 프리릴리즈(Pre-release): 테스트 버전은 -alpha, -beta, -rc 접미사로 구분.
• LTS(Long-Term Support): 장기 유지보수 버전은 별도 명시.

4.2 버전 표시 예시
• v2.3.1 (Build 458)
• v3.0.0-beta.2

5. 문서화 원칙

5.1 Release Note (배포 노트)
• 각 버전의 주요 변경 사항, 버그 수정 내역, 신규 기능, 호환성 이슈를 기록.
• 사용자가 이해할 수 있도록 간결하고 명확하게 작성.

5.2 Changelog (변경 이력)
• 프로젝트 전체의 누적 변경 내역을 시간순으로 정리.
• 개발자 중심으로 세부 기술적 내용을 포함할 수 있음.

6. 권장 지침 요약
1. 버전 번호는 SemVer 체계를 따른다.
2. 빌드번호는 자동 증가 규칙으로 관리한다.
3. 모든 릴리즈는 Git 태그 + Release Note로 기록한다.
4. 정식 릴리즈/테스트 버전/장기 지원 버전을 명확히 구분한다.
5. 변경 내역은 Release Note + Changelog에 반드시 문서화한다.

7. 예시
• 정식 배포: v1.2.5 (Build 134), v1.2.5.134
• 긴급 수정: v1.2.6 (Build 135), v1.2.6.135

• 테스트 버전: v2.0.0-beta.1 (Build 201), v2.0.0.201-beta.1