협업 규칙 (Contributing Guide)

이 문서는 팀의 브랜치 전략 / 이슈 / 커밋 / PR 규칙을 정의한다. 모든 작업은 예외 없이 이슈 생성 → 브랜치 생성 → 커밋 → PR → 리뷰 → 머지 순서를 따른다.

1. 브랜치 전략

1.1 상시 브랜치

브랜치	역할	직접 push
main	배포 브랜치. 항상 동작하는 상태를 유지한다.	금지
develop	통합 브랜치. 모든 기능 브랜치가 여기로 모인다.	금지

• 기능 브랜치는 항상 develop에서 분기하고 develop으로 PR한다.
• 배포 시점에만 develop → main PR을 올린다. (릴리즈 PR)

1.2 작업 브랜치 이름 규칙

<타입>/<이슈번호>-<영문-요약>

타입	용도
feat	새 기능
fix	버그 수정
docs	문서 작업
refactor	동작 변화 없는 코드 개선
test	테스트 코드
chore	설정, 패키지, 배포 스크립트

예시

feat/12-login-api
fix/23-empty-message-500
docs/31-readme-api-spec
chore/3-project-scaffold

• 영문 요약은 소문자 + 하이픈(-)만 사용한다. 3~5 단어를 넘기지 않는다.
• 머지된 브랜치는 원격에서 삭제한다. (기록은 PR에 남는다)

1.3 브랜치 보호 설정 (레포 관리자가 1회 설정)

GitHub Settings → Branches → Add rule 에서 main, develop 각각에 적용한다.

• Require a pull request before merging
• Require approvals — 1명 이상
• Do not allow bypassing the above settings

1.4 머지 방식

Create a merge commit(--no-ff)을 사용한다. Squash merge는 사용하지 않는다.

이유: Squash merge는 브랜치의 개별 커밋을 1개로 합쳐 버리기 때문에, main 히스토리에서 팀원별 커밋 기록이 사라진다. 과제 요건인 "팀원별 유의미한 커밋 10회 이상"을 증명할 수 없게 된다.

2. 커밋 컨벤션

2.1 형식

<type>: <제목 - 50자 이내, 개조식, 마침표 없음>

- 본문은 '무엇을 / 왜' 를 한글로 작성한다 (선택)
- 여러 줄 작성 가능

Refs: #12

• 제목 줄과 본문 사이에는 빈 줄 1개를 넣는다.
• 이슈를 참조할 때는 마지막 줄에 Refs: #이슈번호를 적는다. (이슈를 닫는 것은 커밋이 아니라 PR 본문의 Closes #12 로 처리한다)

2.2 type 목록

type	사용 시점
feat	사용자에게 보이는 새 기능 추가
fix	버그 수정
docs	README, 주석, 문서만 변경
style	포매팅, 세미콜론 등 로직 변화 없는 변경
refactor	동작은 그대로, 코드 구조 개선
test	테스트 추가·수정
chore	빌드/패키지/설정/배포 스크립트

2.3 예시

feat: 로그인 세션 쿠키 발급 기능 구현

- passlib bcrypt 로 비밀번호 검증 후 세션 쿠키를 발급한다
- 비밀번호 불일치 시 401 을 반환한다

Refs: #12

fix: AI 타임아웃 시 500 대신 503 반환하도록 수정
chore: .env.example 추가 및 .gitignore 적용
docs: README 에 환경 변수 키 목록 작성

2.4 커밋 단위 규칙

• 커밋 1개 = 논리적 변경 1개. 하루치 작업을 한 번에 몰아서 커밋하지 않는다.
• 동작하지 않는 코드는 커밋하지 않는다. (작업 브랜치에서도 실행은 되어야 한다)
• .env, *.db, __pycache__ 등은 절대 커밋하지 않는다.
• 목표: 팀원 1인당 유의미한 커밋 10회 이상 (과제 필수 요건)

3. 이슈 컨벤션

3.1 제목 형식

[TYPE] 한글 요약

라벨	제목 접두어	예시
feat	[FEAT]	[FEAT] 로그인 API 구현
bug	[BUG]	[BUG] 빈 메시지 입력 시 500 발생
docs	[DOCS]	[DOCS] README API 명세 작성
chore	[CHORE]	[CHORE] 프로젝트 초기 구조 설정

3.2 라벨 체계

• 작업 종류: feat / bug / docs / chore — 이슈 템플릿이 자동으로 붙인다
• 담당 영역: auth / chat / db / frontend / infra — 이슈 생성 시 직접 고른다

3.3 작성 규칙

• 이슈 하나는 반나절~하루 안에 끝낼 수 있는 크기로 쪼갠다.
• 생성 시 Assignees(담당자) 와 Labels 를 반드시 지정한다.
• 템플릿의 완료 조건은 리뷰어가 검증할 수 있게 구체적으로 적는다.
  • 나쁜 예: "로그인이 잘 된다"
  • 좋은 예: "잘못된 비밀번호로 요청하면 401 과 안내 메시지를 반환한다"

템플릿: .github/ISSUE_TEMPLATE/ 참고

4. PR 컨벤션

4.1 제목

커밋 컨벤션과 동일한 형식을 쓴다.

feat: 로그인 API 구현
fix: 빈 메시지 입력 시 500 발생하던 문제 수정

4.2 본문

.github/pull_request_template.md 가 자동으로 채워진다. 항목을 지우지 말고 채운다.

• 관련 이슈: Closes #12 를 반드시 적는다. (머지 시 이슈가 자동으로 닫힌다)
• 테스트 방법: 리뷰어가 그대로 따라 할 수 있게 명령어/요청 예시까지 적는다.
• UI 변경이 있으면 스크린샷을 첨부한다.

4.3 리뷰 규칙

• Approve 1명 이상을 받아야 머지할 수 있다.
• 리뷰어는 24시간 안에 응답한다. 급한 건은 팀 채널에 공유한다.
• 리뷰 코멘트는 앞에 말머리를 붙여 강도를 표시한다.
  • [필수] 반드시 고쳐야 함 (머지 블로커)
  • [제안] 고치면 좋음 (작성자 판단)
  • [질문] 단순 질문
• 코멘트 반영 후 작성자 본인이 머지한다.

4.4 PR 크기

• 변경량 300줄 이내를 목표로 한다. 넘어가면 이슈를 쪼개서 PR을 나눈다.
• 기능 변경과 리팩터링을 한 PR에 섞지 않는다.

4.5 머지 전 체크리스트

• 로컬에서 서버가 정상 기동되고 해당 기능이 동작한다
• .env, DB 파일 등 민감정보/산출물이 커밋에 포함되지 않았다
• 새 환경 변수를 추가했다면 .env.example 과 README 를 갱신했다
• develop 최신 내용을 반영했고 충돌이 없다

5. 작업 흐름 요약

# 1. 이슈 생성 (#12) 후 develop 최신화
git switch develop
git pull origin develop

# 2. 작업 브랜치 생성
git switch -c feat/12-login-api

# 3. 작은 단위로 커밋
git add app/routers/auth.py
git commit -m "feat: 로그인 세션 쿠키 발급 기능 구현"

# 4. 푸시 후 PR 생성 (base: develop)
git push -u origin feat/12-login-api

# 5. 리뷰 → Approve → Merge commit 으로 머지 → 브랜치 삭제