Hotfix Branch: 모바일 개발에서 생성 및 적용 방법

Hotfix Branch란?

Hotfix Branch는 운영 중인 프로덕션 환경의 심각한 결함을 신속히 수정하기 위해 생성되는 Git의 임시 브랜치입니다. develop에서 분기되어 며칠 또는 몇 주간 지속되는 feature 브랜치와 달리, hotfix는 main/master에서 생성되며 버그 수정에 필요한 기간 동안만 존재합니다.

hotfix의 주요 목적은 심각한 오류 발견부터 프로덕션 수정까지의 시간을 최소화하는 것입니다. 팀은 현재 스프린트나 릴리스 주기가 끝날 때까지 기다리지 않고 즉시 패치를 릴리스합니다. 이는 심각한 버그가 사용자를 차단하고 이탈로 이어질 수 있는 모바일 애플리케이션에서 특히 중요합니다.

Google Play Console에 따르면 Google Play의 업데이트 검토 평균 시간은 2~24시간입니다. App Store의 경우 빠른 검토는 1~4시간이 소요될 수 있습니다. Hotfix 브랜치를 사용하면 검토가 완료되기 전에 수정을 준비하고 승인 후 즉시 릴리스할 수 있습니다.

Hotfix 작동 방식

Hotfix 프로세스는 세 단계로 구성됩니다: main에서 브랜치 생성, 수정, main과 develop에 병합입니다. 일반 수정과의 주요 차이점은 hotfix가 항상 두 브랜치에 모두 병합되어 다음 릴리스에서 수정 사항이 손실되지 않는다는 점입니다.

팀은 hotfix에 새 기능이나 리팩토링을 도입해서는 안 됩니다. 심각한 문제를 해결하는 데 필요한 최소한의 집중 수정만 수행합니다. 이 규칙에서 벗어나면 회귀 위험이 증가하고 패치 릴리스가 지연됩니다.

Hotfix가 필요한 경우

Hotfix는 세 가지 시나리오에서 필요합니다: 심각한 버그가 사용자를 차단하는 경우(충돌, 데이터 손실), 보안 취약점을 즉시 차단해야 하는 경우, 또는 중요한 비즈니스 로직(결제, 인증)이 손상된 경우입니다. 버그가 심각하지 않다면 develop을 통해 정기 릴리스 주기 내에서 수정할 수 있습니다.

모바일 애플리케이션의 경우 아키텍처에서 원격 기능 전환(feature flags)을 허용한다면 hotfix에 서버 측 변경도 포함될 수 있습니다. 이 경우 서버 측에서 수정이 가능하다면 hotfix 브랜치가 최소화되거나 전혀 필요하지 않을 수 있습니다.

브랜칭 모델과 Hotfix의 위치

모든 브랜칭 모델이 hotfix 브랜치를 지원하는 것은 아닙니다. 전통적인 Git Flow는 hotfix를 완전한 브랜치 유형으로 포함하는 반면, 더 현대적인 접근 방식(GitHub Flow, Trunk-based)은 긴급 수정을 다르게 처리합니다.

Git Flow와 Hotfix

Git Flow는 feature 및 release와 함께 hotfix가 내장 브랜치 유형으로 포함된 유일한 모델입니다. Git Flow에서 hotfix는 main에서 생성되고 완료 후 main(버전 태그 포함)과 develop에 모두 병합됩니다. 이는 다음 릴리스에서 수정 사항이 손실되지 않도록 보장합니다.

GitHub Flow와 Trunk-based

GitHub Flow는 hotfix에 별도의 브랜치 유형을 사용하지 않습니다. 대신 개발자가 main에서 일반 feature 브랜치를 만들고 수정을 수행한 후 Pull Request를 엽니다. 검토 및 CI 확인 후 브랜치는 main에 병합되어 즉시 배포됩니다. 장점은 단순함이며, 단점은 긴급 수정을 위한 전용 채널이 없다는 점입니다.

Trunk-based 개발은 (심각한 경우) main에 직접 커밋하고 사후 검토를 의무화하여 hotfix를 처리합니다. 이 접근 방식은 변경 사항이 즉시 프로덕션에 반영되므로 높은 팀 규율과 신뢰할 수 있는 자동화 테스트가 필요합니다.

Hotfix Branch 생성 방법

Hotfix 생성은 메인 브랜치로 전환하고 hotfix/ 접두사가 있는 새 브랜치를 만드는 것으로 시작됩니다. 모바일 애플리케이션의 심각한 버그 수정 예제를 통해 단계별 프로세스를 살펴보겠습니다.

main에서 브랜치 생성

첫 번째 단계 — main으로 전환하고 브랜치가 최신 상태인지 확인합니다. 그런 다음 수정 내용을 반영하는 명확한 이름의 hotfix 브랜치를 생성합니다.

# main으로 전환하고 최신 변경 사항 가져오기
git checkout main
git pull origin main

# hotfix 브랜치 생성
git checkout -b hotfix/crash-on-login

브랜치를 만든 후 수정을 진행할 수 있습니다. 중요한 점: hotfix는 최소한의 변경 사항만 포함해야 합니다. 코드를 리팩토링하거나 새 기능을 추가하지 말고 문제를 해결하는 집중 수정만 수행합니다.

수정 커밋

Hotfix의 커밋 메시지는 문제와 해결 방법을 명확히 설명하는 정보를 제공해야 합니다. 형식: 유형(영역): 간단한 설명 + 트래커의 작업 링크.

# 변경된 파일 추가
git add src/ui/login/LoginActivity.kt

# 설명과 함께 커밋 생성
git commit -m "fix(login): handle null intent on activity resume

Fixes CRASH-142: NullPointerException when LoginActivity
receives onNewIntent after being destroyed by system"

커밋 메시지에는 문제 설명과 작업 링크가 포함되어야 합니다. 이렇게 하면 기록 검색이 쉬워지고 동료가 무엇을 왜 수정했는지 이해하는 데 도움이 됩니다. 모바일 프로젝트의 경우 버그가 발견된 애플리케이션 버전도 포함하는 것이 일반적입니다.

main과 develop에 병합

최종 단계는 hotfix를 main(새 패치 버전 태그 포함)과 develop(다음 릴리스에서 수정 사항 유지)에 병합하는 것입니다. 먼저 main에 태그와 함께 병합한 다음 develop에 병합합니다.

# main에 병합하고 태그 생성
git checkout main
git merge --no-ff hotfix/crash-on-login
git tag -a v2.3.1 -m "Hotfix: crash on login"

# develop에 병합
git checkout develop
git merge --no-ff hotfix/crash-on-login

# 변경 사항을 서버로 푸시
git push origin main --tags
git push origin develop

--no-ff 플래그는 fast-forward로 hotfix를 적용할 수 있었더라도 병합 커밋이 생성되도록 보장합니다. 이는 긴급 수정이 수행되었다는 정보를 보존하고 향후 기록 분석을 용이하게 합니다.

Hotfix, Feature, Release 브랜치의 차이

Hotfix는 목적, 수명 및 병합 규칙 측면에서 feature 및 release 브랜치와 근본적으로 다릅니다. 이러한 차이점을 이해하는 것은 팀에서 Git 프로세스를 올바르게 구성하는 데 중요합니다.

Feature 브랜치는 새 기능을 위한 것입니다. 며칠에서 몇 주까지 지속되며 develop에서 생성되어 develop으로 병합됩니다. feature에는 나중에 squash나 rebase를 통해 압축되는 실험적 커밋을 포함한 여러 커밋이 포함될 수 있습니다.

Release 브랜치는 릴리스를 배포용으로 준비합니다. develop에서 생성되며 안정화 중 발견된 버그가 수정되고 새 기능은 받지 않습니다. 완료 후 release는 main(태그 포함)과 develop에 병합됩니다.

Hotfix는 반면에 develop을 우회하여 main과 직접 생성 및 병합됩니다(수정 후 develop과도 동기화되지만). 최소한의 변경 사항을 포함하며 최소 시간 동안 존재합니다. feature나 release 브랜치는 다음 주기로 연기될 수 있지만 hotfix는 연기할 수 없습니다.

모바일 개발의 경우 이 구분이 특히 중요합니다. App Store와 Google Play는 주요 릴리스와 별도로 패치 버전을 릴리스할 수 있습니다. hotfix 브랜치는 패치 릴리스가 미완료 기능과 혼합되지 않도록 보장합니다.

Hotfix 작업 시 일반적인 실수

Hotfix 작업 시 실수는 긴급 수정의 이점을 무효화할 수 있습니다. Git Flow를 사용하는 팀에서 발생하는 가장 일반적인 다섯 가지 문제를 살펴보겠습니다.

• develop에서 hotfix 생성 — develop에서 hotfix를 생성하면 미완료 기능이 패치에 포함될 수 있습니다. hotfix는 main에서만 생성하여 수정에 안정적인 코드만 포함되도록 해야 합니다.
• 하나의 hotfix에 여러 수정 사항 — 각 수정 사항은 별도의 hotfix 브랜치에 있어야 합니다. 하나의 브랜치에 여러 버그를 혼합하면 코드 검토가 복잡해지고 회귀 위험이 증가하며 필요한 경우 롤백이 어려워집니다.
• develop 병합 누락 — hotfix를 develop에 병합하지 않으면 다음 릴리스에서 수정 사항이 손실됩니다. 팀은 동일한 버그가 다시 나타난 것을 발견하고 다시 수정해야 합니다.
• 잘못된 버전 태그 — hotfix는 패치 증가(v2.3.0 → v2.3.1)를 받아야 하며 마이너(v2.4.0)나 메이저(v3.0.0)가 아닙니다. 시맨틱 버저닝을 위반하면 빌드 시스템이 손상되고 사용자가 혼란스러워집니다.
• CI 검사 부재 — 긴급 hotfix라도 자동화된 테스트를 통과해야 합니다. CI를 건너뛰면 새로운 오류가 발생할 위험이 증가합니다. 핫픽스 브랜치에는 빠른 검사를 수행하는 별도 파이프라인을 두는 것이 좋습니다.

이러한 각 실수는 패치 릴리스 지연이나 프로덕션에서의 새로운 문제 발생으로 이어집니다. 팀은 CONTRIBUTING.md에 hotfix 작업 규칙을 문서화하고 CI/CD 검사를 통해 자동화해야 합니다.