Git Workflow

Git Workflow

브랜치 전략, 커밋·PR·이슈·배포 규칙. 저장소: UMC-PRODUCT/Big-Dipper-iOS

브랜치 전략

Git Flow + 연속 브랜치 파생 지원

• 브랜치명은 {타입}/{이슈번호} (base: develop, PR 대상: develop)
  • 타입은 이슈 템플릿과 1:1 — feat · bug · design · refac · docs · chore
  • 예: docs/1203, feat/1195. 설명형 브랜치명 금지 (docs/repo-rename-links ❌)
  • 대응 이슈가 없으면 브랜치를 만들기 전에 이슈부터 생성한다 (아래 이슈 생성 규칙)
  • PR 제목 끝에 (#이슈번호), 본문에 Closes #이슈번호로 연결
  • ⚠️ 푸시한 브랜치명을 고쳐야 하면 GitHub 브랜치 rename API가 열려 있던 PR을 닫아버린다. rename 후 새 PR을 만들고, 닫힌 PR에 후속 PR 번호를 코멘트로 남긴다.
• 연속 브랜치: feature에서 다음 feature 파생 가능 (티켓 단위 분리)
• PR 대기 중 작업: 승인 대기 중 이전 브랜치에서 다음 브랜치 생성 가능
• 동기화: develop에서 merge 대신 fetch + rebase 사용
• main/develop 직접 푸시 금지 — 반드시 PR을 통해 머지

배포 브랜치 전략

• TestFlight 배포: testFlight/{번호} 브랜치 생성 → testFlight으로 PR 머지 (외부 테스터 빌드는 testflight/external/{번호} 형태도 사용)
• Release 배포: release/{번호} 브랜치 생성 → release로 PR 머지
• 배포 브랜치는 develop에서 분기하여 번호를 순차적으로 매김
• 직접 푸시 금지, 반드시 PR을 통해 머지

커밋 형식

type: 작업 내용

커밋 메시지는 제목 한 줄 + 빈 줄 + 변경사항 bullet list 형식으로 작성합니다.

Type	용도
feat	새 기능
fix	버그 수정
refactor	리팩토링
docs	문서
chore	기타
test	테스트
design	UI/디자인 시스템

⚠️ AI 작성 흔적(attribution) 금지 — 커밋 메시지·PR 제목/본문·이슈 제목/본문·리뷰 코멘트 어디에도 Co-Authored-By: Claude … 트레일러, 🤖 Generated with [Claude Code](...) 푸터, "Created by Claude"/"AI-generated" 같은 문구를 넣지 않습니다.

이슈 생성 규칙

이슈는 제목 접두사 + 라벨 + 이슈 Type + 보드(#3)·우선순위 + 네이티브 Priority·Effort 를 기본으로 모두 채워 생성합니다. 날짜(Start/Target date)는 팀 일정이 정해졌을 때만 채웁니다.

템플릿 (.github/ISSUE_TEMPLATE/)	제목 접두사	라벨	이슈 Type
bug.yml 버그 수정	🐛 Bug:	:bug: Bug	Bug
feature.yml 기능 추가	✨ Feature:	:sparkles: Feature	Feature
design.yml 디자인 반영	🎨 Design:	:lipstick: UI	Task
refactor.yml 리팩토링	♻️ Refactor:	:hammer: Refactor	Task
docs.yml 문서 작업	📄 Docs:	:page_facing_up: Docs	Task
other.yml 기타 작업	🍀 ETC:	:wrench: chore	Task

Type / Priority / Projects

• 이슈 Type(조직 레벨)은 Task / Bug / Feature 3종뿐이라 나머지 템플릿은 Task로 매핑합니다. gh issue create에 --type 플래그가 없으므로 생성 직후 REST로 설정합니다.

  gh api --method PATCH repos/UMC-PRODUCT/Big-Dipper-iOS/issues/{번호} -f type=Feature

• 보드 #3 + 우선순위(Projects v2): iOS 보드는 조직 Projects #3 iOS 개발 프로젝트 템플릿, 우선순위 필드명은 영어가 아닌 한글 우선순위 입니다. project 스코프가 없으면 이 단계만 건너뛰고 (gh auth refresh -s project 후 재적용) Type·라벨은 그대로 적용합니다. gh project item-list JSON은 한글 단일선택 필드를 노출하지 않으므로 검증은 GraphQL fieldValueByName("우선순위")로 합니다.

• 네이티브 이슈 Fields(사이드바 "Fields"): 보드와 별개인 레포 이슈 필드 Priority/Effort/ Start date/Target date. 생성 시 Priority·Effort를 채우고 날짜는 비웁니다 (GraphQL setIssueFieldValue). 보드의 한글 우선순위와 영어 Priority는 서로 다른 필드지만 같은 레벨로 일치시킵니다 — 최고→Urgent/🔥, 높음→High/🔨, 보통→Medium/🤔, 낮음→Low/💬.

• 기본 assignee는 @me. 다른 담당자 지정·미지정은 명시 요청이 있을 때만.

PR 규칙

• 최소 1인 Approve 필수
• main/develop 직접 푸시 금지
• 기본 머지 방식: Squash and Merge
• 배포 PR 예외: testFlight, release 브랜치로의 PR은 Merge Commit 사용 (커밋 히스토리 동기화)
• UI 변경 시 스크린샷/영상 첨부
• CI(Tuist CI)가 초록이어야 머지 — make install → make generate → make test

PR 템플릿

템플릿	용도	섹션
.github/pull_request_template.md (기본)	일반 작업 PR	PR 유형 / 스크린샷·영상 / 작업내용 / 추후 진행 상황 / 리뷰 포인트 / Checklist
.github/PULL_REQUEST_TEMPLATE/deploy.md	배포 PR	배포 유형 / 포함된 변경사항 / Checklist(동작·크래시·TestFlight·심사 가이드라인)

배포 PR은 URL에 ?template=deploy.md 를 붙여 선택합니다.

CI

워크플로	트리거	하는 일
tuist-ci.yml	develop/PR	Secrets 복원·검증 → mise/Tuist 설치 → make generate → make test → Discord 알림
api-coverage.yml	스케줄/수동	Stella apicov로 API 커버리지 리포트 생성

---

관련 문서: Coding Conventions · Build & Run