# 기여 가이드

이 문서는 `Portfolio-Project` 모노레포에서 커밋과 PR을 작성할 때의 기본 규칙을 정리합니다.

## 목표

- 변경 의도가 분명한 커밋을 남긴다.
- PR 하나에는 하나의 목적만 담는다.
- 나중에 커밋 로그와 PR 기록만 봐도 변경 이유를 이해할 수 있게 한다.

## 저장소 구조

- `apps/web`: Next.js 포트폴리오 프론트엔드
- `apps/api`: 향후 백엔드 API 영역
- `packages`: 공용 패키지/타입 영역

## 커밋 가이드

### 기본 원칙

- 한 커밋에는 하나의 목적만 담는다.
- 기능 변경과 포맷팅 변경은 가능하면 분리한다.
- 의미 없는 커밋 메시지(`update`, `final`, `wip`)는 피한다.
- 로컬에서 작업 중인 WIP 커밋은 PR 전에 정리한다.

### 커밋 메시지 형식

```text
type(scope): 한글 요약
```

- `type`과 `scope`는 영어로 유지한다.
- 콜론(`:`) 뒤의 요약 문장은 **기본적으로 한글로 작성**한다.
- 커밋 메시지는 저장소 전반에서 가능한 한 같은 언어(한글)로 통일한다.

### type 예시

- `feat`: 기능 추가
- `fix`: 버그 수정
- `refactor`: 리팩토링
- `style`: UI/스타일 수정
- `docs`: 문서 수정
- `chore`: 설정, 의존성, 기타 정리
- `build`: 빌드/배포 관련 변경
- `test`: 테스트 추가/수정

### scope 예시

- `web`
- `api`
- `packages`
- `repo`
- `ci`

### 좋은 예시

```text
feat(web): 프로젝트 섹션 데이터 구조 추가
style(web): 히어로 영역 타이포 간격 조정
fix(web): 소셜 링크 경로 오류 수정
chore(repo): 워크스페이스 스크립트 정리
docs(repo): 기여 가이드 초안 추가
```

### 언어 규칙

- 커밋 타입(`feat`, `fix`, `docs` 등)은 영어로 유지한다.
- 커밋 요약은 한글로 작성한다.
- PR 제목의 대괄호 타입(`[feat]`, `[fix]` 등)은 영어로 유지하고, 뒤의 설명은 한글로 작성한다.
- PR 본문은 기본적으로 한글로 작성한다.
- 외부 라이브러리명, API명, 파일 경로, 코드 식별자만 필요할 때 영어로 남긴다.

### 피해야 할 예시

```text
update
fix stuff
final commit
wip
misc
```

### 작성 규칙

- `summary`는 짧고 명확하게 작성한다.
- 가능하면 현재형으로 작성한다.
- 변경 이유가 중요한 경우 PR 본문에서 보완한다.

## 브랜치 권장 규칙

권장 형식:

```text
feature/...
fix/...
chore/...
docs/...
```

예시:

```text
feature/web-hero-redesign
fix/web-broken-links
docs/repo-contributing-guide
```

## PR 가이드

### 기본 원칙

- PR 하나에는 하나의 목적만 담는다.
- UI 변경이 있으면 스크린샷 또는 설명을 첨부한다.
- 큰 구조 변경은 왜 필요한지 본문에 적는다.
- 미완성 작업은 Draft PR로 올린다.
- 머지 전 self-review를 먼저 한다.

### PR 제목 형식

```text
[type] 한글 요약
```

- 대괄호 안 타입은 영어로 유지한다.
- 제목의 요약 문장은 한글로 작성한다.

예시:

```text
[feat] 포트폴리오 프로젝트 섹션 추가
[style] 랜딩 페이지 시각 계층 개선
[chore] 모노레포 워크스페이스 구조 정리
```

### PR 본문에 포함할 내용

- 무엇을 바꿨는지
- 왜 바꿨는지
- 리뷰어가 특히 봐야 할 포인트
- UI 변경 시 스크린샷 또는 데모
- 테스트/확인 항목

PR 본문은 특별한 이유가 없으면 한글로 작성한다.

## 모노레포 작업 규칙

- 어떤 영역을 수정했는지 PR 본문에 명시한다.
  - 예: `apps/web`, `apps/api`, `packages`
- 공통 설정을 바꾸면 영향 범위를 함께 적는다.
- 프론트 수정은 가능하면 `web` scope를 사용한다.
- 루트 설정이나 워크스페이스 변경은 `repo` scope를 사용한다.

## 머지 전 체크리스트

- [ ] 불필요한 파일이 포함되지 않았는가?
- [ ] 민감 정보가 커밋되지 않았는가?
- [ ] 변경 목적이 커밋/PR 제목에 드러나는가?
- [ ] UI 변경 시 확인 가능한 자료를 첨부했는가?
- [ ] 최소한 로컬 빌드 또는 주요 화면 확인을 했는가?