# Branching Strategy

## 목적

문서 중심 기획 저장소에서 시작하더라도, 이후 구현 단계까지 이어질 수 있는 브랜치 전략을 미리 고정합니다.

## 기본 원칙

- `main`은 내부 워크스페이스 기준선입니다.
- 커밋은 의미 단위로 작게 유지합니다.
- 내부 기본 원격으로의 푸시는 계속 빠르게 유지합니다.
- 공개용 브랜치는 `main`과 분리된 별도 계보로 관리합니다.
- 릴리즈와 다운로드 서브도메인 갱신은 `release/*` 브랜치에서 마감합니다.

## 브랜치 종류

### `main`

- 내부 워크스페이스 최신 상태
- 자동 반영과 빠른 반복 작업의 기준선
- README, CHANGELOG, 문서 인덱스가 항상 최신이어야 합니다.

### `workspace/main`

- 현재 내부 워크스페이스 기준을 보존하는 백업 성격 브랜치
- 공개용 이력 재구성 전후의 안전 기준점

### `public/main`

- 공개 레포용 큐레이션 브랜치
- 내부 히스토리를 그대로 노출하지 않고, 공개 가능한 이력만 최소 선형 체인으로 유지합니다.
- 공개 배포 직전의 파일/문구/링크/히스토리 검수를 통과한 상태만 반영합니다.
- `main`에서 구조/네이밍 정리가 크게 들어가면 다시 재생성하거나 재큐레이션하는 것을 기본 원칙으로 둡니다.

### `feat/<topic>`

- 기능 개발용 브랜치
- 예: `feat/auth-alpha`, `feat/winui-shell`, `feat/search-index`

### `docs/<topic>`

- 문서 보강/개편 전용 브랜치
- 예: `docs/readme-overhaul`, `docs/release-playbook`

### `release/<version>`

- 릴리즈 마감용 브랜치
- 예: `release/v0.1.0-alpha.1`
- 아래 항목을 함께 정리합니다.
  - 빌드 산출물
  - `CHANGELOG.md`
  - README 상태 반영
  - 다운로드 경로 점검

### `hotfix/<topic>`

- 배포 후 긴급 수정
- 예: `hotfix/download-link`, `hotfix/auth-token-rotation`

### `spike/<topic>`

- 실험/검증
- 장기 유지 코드로 합칠지 미정인 경우만 사용

## 머지 원칙

- 개인 저장소 기준으로도 PR 스타일 설명을 남깁니다.
- `main` 머지 전 확인 항목:
  - README가 최신 상태인가
  - `문서/`의 결정과 충돌하지 않는가
  - CHANGELOG 반영이 필요한가
  - 다운로드/릴리즈 경로 영향이 있는가
- `public/main` 반영 전 추가 확인 항목:
  - 공개 부적합 링크나 내부 경로가 남아 있지 않은가
  - AI/프롬프트/에이전트 같은 메타 흔적이 남아 있지 않은가
  - 공개용 커밋 이력이 과도하거나 어색하지 않은가
  - 공개 릴리즈 문구가 현재 구현 상태를 넘어서지 않는가
  - `.workspace-*` 경로의 비공개 정책/시크릿이 추적 대상에 섞이지 않았는가

## 커밋 규칙

- 권장 접두사:
  - `docs:`
  - `feat:`
  - `fix:`
  - `release:`
  - `chore:`
- 예:
  - `docs: define korean-first signup policy`
  - `feat: scaffold winui shell`
  - `release: prepare alpha download endpoint`

## 릴리즈 운영 규칙

릴리즈 브랜치에서는 아래를 반드시 같이 처리합니다.

1. Windows 빌드 생성
2. VPS 업로드
3. `https://download-vstalk.phy.kr` 동작 확인
4. README 버전/상태 갱신
5. CHANGELOG 갱신
6. 태그 생성
7. `main` 반영

공개 릴리즈는 아래 순서를 따릅니다.

1. 내부 기본 원격 반영
2. 명시적 요청이 있을 때만 제2 공개 레포 반영
3. 다시 명시적 요청이 있을 때만 제3 공개 레포 반영

제3 공개 레포는 항상 제2 공개 레포보다 늦게 공개하며, 제2 공개 레포 경로를 함께 명시합니다.

## 문서 갱신 규칙

다음 변화가 있으면 README와 문서를 같이 갱신합니다.

- 제품 방향 변경
- 가입 방식 변경
- 릴리즈 방식 변경
- 다운로드 경로 변경
- 우위/패리티 판단 변경

즉, 구현만 바꾸고 문서를 방치하지 않습니다.
