Skip to content

DEVELOP_PR_GUIDE.md

Latest commit

 

History

History
371 lines (265 loc) · 9.72 KB

DEVELOP_PR_GUIDE.md

File metadata and controls

371 lines (265 loc) · 9.72 KB

Pull Request (PR) 작성 가이드라인

효과적인 코드 리뷰를 위해 명확하고 읽기 쉬운 PR을 작성하세요. 이 가이드는 팀원들이 빠르게 변경 사항을 이해하고 검토할 수 있도록 돕습니다.

💡 핵심 원칙: PR은 코드 자체가 아닌 변경의 맥락과 의도를 전달하는 것입니다.

📌 PR 작성 전 필독사항

실제 코드 변경사항은 git diff로 확인하세요

PR을 작성하기 전에 아래 명령어로 현재 브랜치와 develop 브랜치 간의 정확한 차이를 확인하세요:

git diff develop

이 명령어의 결과가 PR 작성의 가장 정확한 기준이 됩니다. PR 설명은 이 diff 내용을 바탕으로 작성해야 합니다.

커밋 메시지는 참고만 하세요

git log로 보이는 커밋 메시지는 단순 참고용입니다. 실제 PR 설명은 git diff develop의 결과를 기반으로 작성하세요.

# 커밋 이력 확인 (참고용)
git log develop..HEAD --oneline

왜? 커밋은 과정을 기록하고, PR은 최종 결과를 설명하기 때문입니다.

확인 대상 용도 신뢰도
git diff develop PR 작성의 정확한 기준 ⭐⭐⭐⭐⭐
git log 개발 과정의 맥락 ⭐⭐⭐

1️⃣ PR 제목

형식

[타입] 설명 (이슈 번호)

타입

  • Feat - 새로운 기능 추가
  • Fix - 버그 수정
  • Refactor - 코드 구조 개선
  • Docs - 문서 변경
  • Test - 테스트 코드 추가
  • Chore - 빌드, 의존성 등 변경
  • Style - 코드 포맷팅

예시

✅ 좋은 예시 ❌ 피해야 할 예시
[Feat] 프리셋 필터 CSV 다운로드 API 추가 (#111) feature 추가
[Fix] 프리셋 필터 조회 오류 해결 (#95) 버그 수정했습니다
[Refactor] 고객 타겟팅 로직 최적화 코드 리팩토링

2️⃣ PR 설명 - 마크다운 헤딩 구조

PR 설명은 명확한 헤딩 계층으로 정보를 구조화합니다. 다음 형식을 따라 작성하세요.

📐 헤딩 레벨 규칙

  • # (h1): 메인 섹션 (📝 어떤 변경인가요?, 🎯 변경의 목적, 등)
  • ## (h2): 하위 섹션 (새로운 기능, 배경, 목적, 등)
  • ### (h3): 세부 항목 (1. 환경별 설정 분리, 2. 마이그레이션 프로세스, 등)

❌ 피해야 할 것:

  • 볼드체(**)로 제목 표현
  • 들여쓰기로 계층 구조 표현
  • ### (h3)를 메인 섹션으로 사용

📝 어떤 변경인가요?

목적: 이 PR이 추가/수정/삭제하는 기능을 간결하게 설명

작성 형식:

# 📝 어떤 변경인가요?

## 새로운 기능
- 기능 1 설명
- 기능 2 설명

## 주요 추가/수정 항목
- 파일명: 변경 내용
- 파일명: 변경 내용

예시:

# 📝 어떤 변경인가요?

## 새로운 기능
- GET /api/v1/preset-filters/{presetFilterId}/targets/export/csv 엔드포인트 추가
- 프리셋 필터의 고객 타겟 데이터를 CSV로 다운로드 가능

## 주요 추가/수정 항목
- CsvExportService 클래스 추가
- PresetFilterNotFoundException 예외 클래스 추가
- PresetFilterController에 exportTargetsCsv() 메서드 추가
✅ 해야 할 것 ❌ 하지 말 것
#으로 메인 섹션 구분 ###이나 볼드체 사용
##로 하위 항목 구분 들여쓰기로 계층 표현
명확한 클래스/메서드명 포함 장황한 설명

🎯 변경의 목적은 무엇인가요?

목적: 변경이 왜 필요했는지 비즈니스/기술적 배경 설명

작성 형식:

# 🎯 변경의 목적은 무엇인가요?

## 배경
문제 상황이나 요구사항 설명 (1-2줄)

## 목적
- 목적 1
- 목적 2
- 목적 3

예시:

# 🎯 변경의 목적은 무엇인가요?

## 배경
마케팅 팀에서 프리셋 필터로 조회된 고객 데이터를 외부 시스템으로 내보낼 필요가 있음

## 목적
- 고객 목록을 CSV로 다운로드하여 이메일 마케팅 플랫폼과 통합
- 수동 데이터 복사 작업 제거로 업무 효율성 향상
- 대규모 고객 데이터 관리 자동화
✅ 해야 할 것 ❌ 하지 말 것
#으로 메인 섹션 시작 ### 사용
비즈니스 가치 명확히 기술 세부사항 먼저
##로 배경/목적 구분 볼드체 사용

🔧 어떻게 변경되었나요?

목적: 기술적 구현 방식을 정확하게 설명

작성 형식:

# 🔧 어떻게 변경되었나요?

## 새로운 파일
- 파일명 - 설명

## 수정된 파일

| 파일 | 변경 사항 |
|------|---------|
| 파일1 | 변경내용 |
| 파일2 | 변경내용 |

## 기술적 상세

### 1. 세부 항목 1
설명

### 2. 세부 항목 2
설명

예시:

# 🔧 어떻게 변경되었나요?

## 새로운 파일
- CsvExportService - CSV 파일 생성 및 포맷팅 담당
- PresetFilterNotFoundException - 프리셋 필터 미존재 예외 처리

## 수정된 파일

| 클래스 | 변경 사항 |
|--------|---------|
| PresetFilterController | /targets/export/csv 엔드포인트 추가 |
| PresetFilterApplicationService | 타겟 조회 및 CSV 변환 로직 추가 |

## 기술적 상세

### 1. 엔드포인트 구현
- Spring의 @GetMapping으로 파일 다운로드 엔드포인트 구현

### 2. 스트리밍 처리
- HttpServletResponse를 사용한 CSV 스트리밍으로 메모리 효율성 확보
✅ 해야 할 것 ❌ 하지 말 것
#, ##, ### 계층 구조 볼드체나 들여쓰기
테이블로 정보 정리 모든 파일 나열
핵심 로직만 강조 자명한 변경사항 설명

✅ 테스트 방법

목적: 리뷰어가 기능을 직접 검증할 수 있도록 구체적인 테스트 방법 제시

작성 형식:

# ✅ 테스트 방법

## 로컬 환경 테스트
```bash
명령어

검증 항목

  • 항목 1
  • 항목 2

**예시:**
```markdown
# ✅ 테스트 방법

## API 테스트
```bash
curl -X GET "http://localhost:8080/api/v1/preset-filters/{id}/targets/export/csv" \
  -H "Authorization: Bearer {token}" \
  -o "targets.csv"

검증 항목

  • 유효한 프리셋 필터 ID로 요청 시 CSV 파일이 정상 다운로드됨
  • CSV 파일에 타겟 전화번호가 올바르게 포함되어 있음
  • 존재하지 않는 프리셋 필터 ID로 요청 시 404 에러 반환

| ✅ 해야 할 것 | ❌ 하지 말 것 |
|----------|----------|
| `#`으로 메인 섹션 | `###` 사용 |
| `##`로 하위 구분 | 볼드체 사용 |
| 실행 가능한 명령어 | 추상적 설명 |

---

## ⚠️ 특이 사항

**목적:** 리뷰어가 특별히 주의할 사항을 미리 알림

**작성 형식:**
```markdown
# ⚠️ 특이 사항

## 🔒 보안
- 보안 고려사항

## 📋 배포 시 주의사항

### 사전 작업 필수
1. 작업 1
2. 작업 2

### 기타 사항
- 사항 1
- 사항 2

## ⚡ 성능
- 성능 고려사항

예시:

# ⚠️ 특이 사항

## 🔒 보안
- Prod DB 자격증명은 Secret Manager에서 관리
- Cloud SQL Proxy를 통한 안전한 연결 (Public IP 불필요)

## 📋 배포 시 주의사항

### 사전 작업 필수
1. Secret Manager에 DB 자격증명 생성
2. Cloud Build 서비스 계정에 권한 부여

### Baseline 설정
- V1~V10은 "이미 적용됨"으로 간주
- V11부터 새로운 마이그레이션 적용

## ⚡ 성능
- 대량 데이터 처리 시 메모리 사용량 증가 가능
- 스트리밍 방식으로 메모리 효율성 최대화
✅ 해야 할 것 ❌ 하지 말 것
#으로 메인 섹션 ### 사용
##로 카테고리 구분 볼드체만 사용
###로 세부 항목 들여쓰기로 계층

🔗 관련 이슈

목적: PR과 이슈 추적 시스템 연동

작성 형식:

# 🔗 관련 이슈

close #이슈번호

작성 방법:

  • close #이슈번호 - PR 병합 시 자동으로 이슈 종료
  • Relates to #번호 - 관련된 이슈 참조

예시:

# 🔗 관련 이슈

close #111
Relates to #100, #102

📋 PR 작성 체크리스트

작성 완료 전 다음 항목을 확인하세요:

  • 제목이 [타입] 설명 (#번호) 형식인가?
  • 모든 메인 섹션이 # (h1)로 시작하는가?
  • 하위 섹션이 ## (h2)로 구분되어 있는가?
  • 세부 항목이 ### (h3)로 구분되어 있는가?
  • 볼드체나 들여쓰기 대신 헤딩을 사용했는가?
  • 어떤 변경? 섹션에 구체적인 엔드포인트/클래스명이 있는가?
  • 변경의 목적? 섹션에 비즈니스 가치가 명시되어 있는가?
  • 어떻게 변경? 섹션에 테이블과 기술 설명이 있는가?
  • 테스트 방법? 섹션에 실행 가능한 명령어와 검증 항목이 있는가?
  • 특이 사항? 섹션에 성능/보안/배포 항목이 있는가?
  • 마크다운 포맷팅이 깔끔한가? (헤딩, 테이블, 불릿, 이모지 활용)
  • 관련 이슈를 명시했는가?

🎓 좋은 PR의 특징

✨ 명확성 - 리뷰어가 코드 없이도 변경을 이해할 수 있음 ✨ 구조화 - 명확한 헤딩 계층으로 정보 구조화 ✨ 구체성 - 추상적 표현 대신 구체적인 예시와 수치 포함 ✨ 액션성 - 리뷰어가 바로 따라할 수 있는 테스트 방법 제공 ✨ 배려 - 리뷰어의 시간을 존중하는 간결한 구성

Remember: 좋은 PR은 빠른 리뷰를 만들고, 빠른 리뷰는 빠른 배포를 가능하게 합니다. 💪