[Git & Github] PR(Pull Request) 문서 작성 요령

 

좋은 Pull Request(PR) 문서는 "리뷰어가 코드를 이해하는 시간을 줄여주는 문서"입니다. 리뷰어는 대부분 다음 4가지를 알고 싶어 합니다.

1. 왜 변경했는가? (Why)
2. 무엇이 변경되었는가? (What)
3. 어떻게 확인하면 되는가? (How to Review/Test)
4. 영향 범위는 어디까지인가? (Impact)

개인적으로는 아래와 같은 템플릿을 가장 많이 추천합니다.

## 📌 Summary
- 이번 PR에서 변경한 내용을 한두 문장으로 요약합니다.

## 🎯 Background
- 왜 이 변경이 필요한지 설명합니다.
- 관련 이슈나 버그, 요구사항을 적습니다.
- Closes #123

## 🔨 Changes
- 주요 변경 사항을 항목별로 작성합니다.
- API 변경
- UI 변경
- 리팩토링
- 테스트 코드 추가

## 🧪 How to Test
1. 프로젝트 실행
2. 특정 페이지 이동
3. 특정 버튼 클릭
4. 기대 결과 확인

## 📷 Screenshots (Optional)
- UI 변경이 있다면 Before / After 이미지 첨부

## ⚠️ Notes
- 리뷰 시 중점적으로 봐주었으면 하는 부분
- 아직 해결하지 못한 사항
- 추후 작업 예정

 

---

좋은 예시

❌ 좋지 않은 PR

버그 수정했습니다.

 

리뷰어는 아래 내용을 전혀 알 수 없습니다.

• 무엇을 수정했는지
• 왜 수정했는지
• 어떻게 테스트하는지

---

✅ 좋은 PR

## Summary
사용자 로그인 후 간헐적으로 발생하던 Session 만료 오류를 수정했습니다.

## Background
토큰 갱신 시 Refresh API 호출 순서가 잘못되어
만료된 Access Token으로 요청하는 문제가 있었습니다.

## Changes
- Token Refresh 로직 수정
- Axios Interceptor 개선
- Session 관련 테스트 추가

## How to Test
1. 로그인
2. Access Token 만료 대기
3. API 호출
4. 정상적으로 Refresh 후 요청이 성공하는지 확인

## Notes
Interceptor 로직 변경이 있으므로 인증 관련 코드를 중점적으로 리뷰 부탁드립니다.

 

---

규모가 큰 PR이라면 추가하면 좋은 항목

• Architecture
  • 어떤 설계를 변경했는지
• Migration
  • DB Migration 여부
  • 환경 변수 추가 여부
• Breaking Changes
  • 하위 호환성 깨짐 여부
• Performance
  • 성능 영향
• Risk
  • 배포 시 위험 요소
• Rollback
  • 문제 발생 시 되돌리는 방법

예를 들어,

## Risk
- 인증 로직이 변경되어 로그인 기능에 영향이 있을 수 있습니다.

## Rollback
- 이전 Interceptor 구현으로 되돌리면 됩니다.

 

---

리뷰어 입장에서 가장 좋아하는 PR

다음 네 가지가 빠짐없이 포함되어 있으면 리뷰가 훨씬 수월합니다.

 

항목	목적
Why	왜 변경했는지
What	무엇을 변경했는지
How	어떻게 테스트하는지
Notes	어디를 집중해서 리뷰하면 되는지

 

특히 팀에서 PR을 많이 주고받는다면, "Summary → Background → Changes → How to Test → Notes" 정도로 통일된 템플릿을 사용하는 것을 추천합니다. 이 정도 구성만 유지해도 리뷰 속도와 품질이 눈에 띄게 좋아지는 경우가 많습니다.