[CardBenePICK] 기여 가이드

이 프로젝트에 기여해주셔서 감사합니다! 이 문서는 원활한 협업을 위한 규칙과 가이드를 제공합니다. 모든 구성원은 이 문서를 숙지하고 따라주시기 바랍니다.

🚀 핵심 협업 원칙

1. dev 브랜치 타겟: 모든 PR은 dev 브랜치를 타겟으로 합니다. (main 브랜치로 직접 PR 금지)
2. 코드 리뷰: 모든 코드는 최소 1명 이상의 리뷰어에게 승인(Approve)을 받아야 Merge할 수 있습니다.
3. 컨벤션 준수: 브랜치, 커밋, PR 생성 시 정해진 컨벤션을 따릅니다.

---

🌳 1. 브랜치 전략

• main:
  • [운영/배포] 브랜치입니다.
  • 오직 dev 브랜치에서 정식 릴리즈된 버전만 Merge 됩니다.
  • 절대 직접 커밋하거나 이 브랜치로 PR을 보내지 않습니다.
• dev:
  • [개발/통합] 브랜치입니다.
  • 다음 릴리즈를 준비하는 모든 기능이 통합되는 메인 개발 브랜치입니다.
  • 모든 feature 브랜치는 dev를 타겟으로 PR을 보냅니다.
• feature/[description]:
  • [기능 개발] 브랜치입니다.
  • 반드시 dev 브랜치에서 생성합니다.
  • 기능 설명은 간결한 영어로 작성합니다. (예: feature/login-api)
• fix/[description]:
  • [버그 수정] 브랜치입니다.
  • dev 브랜치에서 발생한 버그를 수정할 때 사용합니다. (예: fix/login-validation)
• hotfix/[description]:
  • [긴급 수정] 브랜치입니다.
  • main 브랜치에서 직접 생성하며, 수정 완료 후 main과 dev 브랜치 모두에 Merge해야 합니다.

---

✍️ 2. 커밋 컨벤션 (Conventional Commits)

모든 커밋 메시지는 'Conventional Commits' 양식을 따릅니다. 이는 변경 로그 자동화와 명확한 히스토리 관리를 위함입니다.

1. 커밋 메시지 기본 구조

커밋 메시지는 제목 (Subject), 본문 (Body), 꼬리말 (Footer) 세 부분으로 구성되며, 제목은 필수입니다.

2. Type (제목) 규칙

• Type: 반드시 영어 소문자로 작성합니다.

• 한글 요약 설명:

  • 작업 내용을 명확하게 한글로 요약합니다.
  • 작업이 완료된 이슈가 있다면 (Closes #이슈번호)를 덧붙입니다.
  • "을/를 추가함", " 수정함"과 같이 서술형으로 작성합니다.
  • 제목 끝에 마침표(.)를 찍지 않습니다.

• (예시) feat: 로그인 API 엔드포인트 추가 (Closes #123)

• (예시) fix: 유저 이메일 유효성 검사 오류 수정 (Closes #124)

3. 본문 (Body) 규칙 (선택)

• 제목만으로 설명이 부족할 때 작성합니다.
• 무엇을, 왜, 어떻게 변경했는지 상세히 설명합니다.
• 여러 줄로 작성할 수 있습니다.

4. 꼬리말 (Footer) 규칙 (선택)

• BREAKING CHANGE:와 같이 기존 기능에 영향을 미치는 큰 변경 사항이 있을 때 명시합니다.

---

🔹 Type 정의 및 예시

다음 7가지 Type 중 하나를 골라 사용합니다.

• feat: 새로운 기능 추가 (기존 기능 개선, 고도화 포함)
  • 예: feat: 로그인 API 엔드포인트 추가
  • 예: feat: 메인 화면 UI 고도화
  • 예: feat: 검색 API 응답 속도 개선
• fix: 버그 수정
  • 예: fix: 유저 이메일 유효성 검사 오류 수정
  • 예: fix: 모바일 화면 레이아웃 깨짐 수정
  • 예: fix: API 요청 시 500 에러 해결
• docs: 문서 수정 (README.md, API 문서 등)
  • 예: docs: README.md 실행 방법 업데이트
• style: 코드 스타일 수정 (포매팅, 세미콜론 등 기능 변경 없는 수정)
  • 예: style: Prettier 포매팅 적용
• refactor: 코드 리팩토링 (기능 변경 없이 코드 구조 또는 성능 개선)
  • 예: refactor: AuthService 로직 분리
  • 예: refactor: 중복 코드 유틸 함수로 추출
  • 예: refactor: N+1 쿼리 문제 해결
  • 예: refactor: LLM 프롬프트 구조 최적화 (토큰 사용량 감소)
  • 예: refactor: OpenAI API 호출 로직을 Anthropic API로 교체 (내부 구현 변경)
• test: 테스트 코드 추가 또는 수정
  • 예: test: 로그인 API 테스트 케이스 추가
• chore: 빌드 설정, 의존성 관리 등 기타 잡일
  • 예: chore: react-query 라이브러리 추가

---

📬 3. Pull Request (PR) 프로세스

1. PR 생성: feature 또는 fix 브랜치에서의 작업이 완료되면 dev 브랜치로 PR을 생성합니다.
2. 템플릿 작성: PULL_REQUEST_TEMPLATE.md 양식에 맞춰 모든 항목을 상세히 기재합니다.
3. 리뷰어 지정: 각 리포지토리의 CODEOWNERS를 참고하거나, 적절한 팀원을 리뷰어로 지정합니다.
4. Draft PR 활용: 작업이 진행 중이지만 미리 공유하고 싶다면 'Draft PR'을 생성합니다.
5. 셀프 리뷰: PR 생성자는 리뷰를 요청하기 전, 'Files changed' 탭에서 자신의 코드를 스스로 리뷰하며 불필요한 파일이나 디버그 코드가 없는지 확인합니다.
6. CI 통과: PR은 자동으로 실행되는 CI(Continuous Integration, 빌드/테스트)를 반드시 통과해야 합니다.
7. Merge: 최소 1명 이상의 'Approve'를 받고 CI가 통과되면, PR을 생성한 사람이 직접 "Squash and merge" 방식으로 Merge 합니다.
   • (Squash and merge: PR의 여러 커밋을 하나로 합쳐 dev 브랜치에 반영)