“브랜치 운용 규칙 + 커밋/릴리스 체계”를 실전용으로 정리

1) 브랜치 전략 (간단·실무형)

• 영구 라인
  • master : 항상 배포 가능한 상태(프로덕션과 동기)
  • develop(선택) : 여러 기능을 모아 통합 테스트할 때만 사용. 소규모면 생략 가능
• 작업 라인
  • feature/<모듈>-<기능> : 기능 개발 (예: feature/ai-ask-author, feature/epub-multi)
  • hotfix/<이슈키> : 운영 긴급 수정 (예: hotfix/500-poet-detail)
  • backup/<YYYY-MM-DD> : 대청소 전 스냅샷(며칠 확인 후 삭제)

예시(프로젝트 맥락)

• feature/oukwon-ui (작품관 UI 개선)
• feature/epub-batch (여러 단편 묶음 전자책)
• feature/ai-ask-author (AI “작가에게 묻는다”)
• feature/users-admin-menu (관리자 메뉴/표시)
• feature/chronology-timeline (작가 연보/연표)

2) 브랜치 라이프사이클

1. 만들기(또는 GitHub에서 먼저 생성 → git fetch → git checkout -b ... origin/...)
2. git checkout master && git pull git checkout -b feature/epub-batch
3. 초반 커밋(뼈대 + TODO)
   • 디렉터리/파일 구조만 만들고 TODO 주석 남김
   • 예: oukwon/views_epub_batch.py에 함수 골격과 TODO
4. 점진 구현 → 작은 커밋 단위로 누적
5. 마무리
   • git rebase master로 최신화
   • 스쿼시 머지로 기록 단순화 → 브랜치 삭제

3) 머지 방식 원칙

• 기본: Squash merge (히스토리 깔끔, 이슈 트래킹 쉬움)
• git checkout master git merge --squash feature/epub-batch git commit -m "feat(epub): 다중 작품 EPUB 발간 기능 1차" git push && git branch -d feature/epub-batch git push origin --delete feature/epub-batch
• 충돌 방지: 머지 전 반드시
• git checkout feature/epub-batch git fetch --all --prune git rebase master

4) 커밋 메시지 규칙 (프로젝트 맞춤)

형식: 타입(영역): 한 줄 요약
타입: feat, fix, docs, refactor, style, test, chore
영역 예: epub, ai, oukwon, users, timeline, infra

예시

• feat(oukwon): 작품 상세에 ‘전자책 만들기’ 버튼 추가
• fix(users): 로그아웃 후 홈으로 리다이렉트
• refactor(epub): 파일 저장 경로 /tmp로 이동

5) 태그/릴리스

• 배포 시점마다 태그
• git checkout master && git pull git tag -a v0.4.0 -m "작품관 UI, 다중 EPUB, 관리자 메뉴" git push origin v0.4.0
• 패치 핫픽스는 v0.4.1 식으로 증가

6) 정기 정리 루틴

• 매 작업 시작:
  git fetch --all --prune && git checkout master && git pull
• 2주/스프린트 종료 시:
• git branch --merged master | egrep -v '^\*| master|backup/' | xargs -n1 git branch -d
• .gitignore 점검(필수): venv/, media/, __pycache__/, *.sock, staticfiles/, .env

7) TODO 주석 템플릿 (파편화 방지)

# TODO[epub-batch][MVP]: ids 파라미터 검증, 빈 선택 예외 처리
# TODO[epub-batch][Perf]: 대용량 작업 시 비동기 큐 고려(Celery)
# TODO[epub-batch][UX]: 완료 후 다운로드 링크/토스트 노출

• 대괄호에 기능키/우선순위를 넣어 검색과 정리 용이

8) Git ↔ Sourcetree 매핑(핵심만)

• 새 브랜치: 좌상단 Branch 버튼 → 이름 입력
• Rebase: 브랜치 우클릭 → Rebase onto… → master
• Squash: PR에서 Squash and merge 또는 로컬 --squash 후 푸시
• Prune: Fetch 창에서 Prune tracking branches 체크

9) 협업 체크리스트(1인 개발에도 유효)

• 기능 시작 전 이름 규칙 지키며 브랜치 생성
• 초반 커밋은 뼈대+TODO만
• 커밋은 작은 단위, 메시지는 의도 중심
• 머지 전 rebase master로 충돌 미리 해결
• 머지는 squash, 끝나면 브랜치 삭제
• 배포는 태그로 기록

진행중인 오유권문학관 프로젝트