Skip to content

Commit 9cd9fcb

Browse files
kimchanhyung98kimchanhyung98
authored
Merge pull request #14 from kimchanhyung98/feature/branch-name-check
feat(github): add branch naming policy and validation system
2 parents 835f7c4 + 0cec1ac commit 9cd9fcb

File tree

7 files changed

+225
-84
lines changed

7 files changed

+225
-84
lines changed

‎.github/docs/branch-name-guide.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# 브랜치명 검증 가이드
2+
3+
**실행 시점**: Pull Request 생성/수정 시 (자동)
4+
**워크플로우**: `.github/workflows/branch-name-check.yml`
5+
**형식**: `<type>/<description>` 또는 `<type>/<domain>/<description>`
6+
7+
## 허용 타입
8+
9+
| 타입 | 설명 | 예시 |
10+
|------------|----------------------|----------------------------------|
11+
| `feature` | 새로운 기능 개발 | `feature/user-authentication` |
12+
| `fix` | 버그 수정 | `fix/login-bug` |
13+
| `hotfix` | 긴급 버그 수정 | `hotfix/critical-security-issue` |
14+
| `release` | 릴리스 준비 | `release/v1.0.0` |
15+
| `refactor` | 코드 리팩토링 | `refactor/auth-logic` |
16+
| `docs` | 문서 업데이트 | `docs/installation-guide` |
17+
| `test` | 테스트 추가 | `test/unit-tests` |
18+
| `chore` | 유지보수 작업 | `chore/update-deps` |
19+
| `style` | 스타일 개선 | `style/format-code` |
20+
| `copilot` | GitHub Copilot 지원 개발 | `copilot/add-validation` |
21+
| `claude` | Claude AI 지원 개발 | `claude/refactor-api` |
22+
23+
## 보호 브랜치 (검사 제외)
24+
25+
`main`, `master`, `develop`, `staging`
26+
27+
## 브랜치명 규칙
28+
29+
### ✅ 올바른 형식
30+
31+
- **타입**: 위 표의 허용된 타입 중 하나 사용
32+
- **구분자**: `/` (슬래시) 사용
33+
- **허용 문자**: 소문자(a-z), 숫자(0-9), 하이픈(-), 점(.)
34+
35+
#### 2단계 형식 (기본)
36+
37+
```bash
38+
✅ feature/user-authentication
39+
✅ fix/404-error
40+
✅ copilot/add-validation
41+
✅ claude/refactor-api
42+
✅ hotfix/security-patch-2024
43+
✅ release/1.0.0
44+
```
45+
46+
#### 3단계 형식 (도메인 포함)
47+
48+
```bash
49+
✅ feature/frontend/user-authentication
50+
✅ fix/api/null-response
51+
✅ refactor/backend/auth-logic
52+
✅ docs/api/endpoint-guide
53+
✅ test/integration/payment-flow
54+
✅ fix/api/404-error
55+
```
56+
57+
### ❌ 잘못된 형식
58+
59+
```bash
60+
❌ Feature/Frontend/User-auth # 타입, 도메인, 설명에 대문자 사용 금지
61+
❌ my-feature # 타입 누락
62+
❌ feature/add_function # 언더스코어 사용 금지
63+
❌ feature/a/b/c # 4단계 이상 금지
64+
❌ feature/ # 설명 누락
65+
```
66+
67+
## 검증 계층
68+
69+
| 계층 | 시점 | 우회 가능 여부 |
70+
|----------------|-----------------|----------------------------|
71+
| 로컬 Husky | `git push` 실행 시 | ✅ `--no-verify` 플래그로 우회 가능 |
72+
| GitHub Actions | PR 생성/수정 시 | ❌ 필수 체크 (우회 불가) |
73+
74+
## Branch Protection 설정 권장
75+
76+
**Settings → Branches → Branch protection rules**
77+
78+
1. `main` 브랜치에 보호 규칙 추가
79+
2. **Require status checks to pass before merging** 활성화
80+
3. **validate-branch-name** 체크 필수로 지정
81+
82+
이렇게 설정하면 브랜치명 규칙을 위반한 PR은 병합할 수 없습니다.

‎.github/docs/pull-request-guide.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Pull Request 작성 가이드
2+
3+
제목 형식 : `<type>(<scope>): <description>`
4+
5+
## 규칙
6+
7+
- **소문자**로 시작
8+
- **명령형 현재 시제** 사용 (add, 과거형 added가 아님)
9+
- 마침표 **없음**
10+
- **50자 이내** 권장
11+
12+
## 🏷️ Types
13+
14+
| Type | 설명 | 예시 |
15+
|------------|------------|----------------------------------------------|
16+
| `feat` | 새로운 기능 추가 | `feat(user): add email verification` |
17+
| `fix` | 버그 수정 | `fix(payment): resolve timeout error` |
18+
| `docs` | 문서 변경 | `docs(api): add OpenAPI spec` |
19+
| `style` | 코드 스타일 변경 | `style(user): format with prettier` |
20+
| `refactor` | 코드 리팩토링 | `refactor(order): extract calculation logic` |
21+
| `test` | 테스트 추가/수정 | `test(user): add authentication tests` |
22+
| `chore` | 기타 변경사항 | `chore(deps): upgrade Laravel to 12.1` |
23+
| `perf` | 성능 개선 | `perf(database): optimize user query` |
24+
| `ci` | CI/CD 변경 | `ci(github): add deployment workflow` |
25+
| `build` | 빌드 시스템 변경 | `build(docker): update PHP to 8.5` |
26+
| `revert` | 이전 커밋 되돌리기 | `revert(payment): revert payment feature` |
27+
28+
## 🎯 Scopes
29+
30+
| Scope | 설명 |
31+
|-----------------------------------------|---------|
32+
| `user`, `product`, `order`, `payment` | 도메인 관련 |
33+
| `auth`, `api`, `database`, `middleware` | 컴포넌트 관련 |
34+
| `service`, `controller`, `model` | 레이어 관련 |
35+
| `docker`, `deps`, `config`, `github` | 인프라 관련 |
36+
37+
## 예시
38+
39+
```
40+
feat(user): add email verification
41+
fix(payment): resolve timeout error
42+
refactor(order): extract calculation logic
43+
docs(api): add OpenAPI specification
44+
chore(deps): upgrade Laravel to 12.1
45+
```

.github/repository-copilot-guide.md renamed to .github/docs/repository-copilot-guide.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@
44

55
레포지토리에서 Copilot, Coding agent의 MCP (Model Context Protocol) 서버 설정입니다.
66

7-
| 서버 | 용도 | 설명 |
8-
|------|------|------|
9-
| **context7** | 라이브러리 문서 조회 | 최신 프레임워크 및 라이브러리 문서 참조 |
10-
| **playwright** | 브라우저 자동화 | E2E 테스트 및 브라우저 테스트 지원 |
11-
| **sequential-thinking** | 복잡한 문제 해결 | 단계별 분석 및 체계적 사고 지원 |
7+
| 서버 | 용도 | 설명 |
8+
|-------------------------|-------------|------------------------|
9+
| **context7** | 라이브러리 문서 조회 | 최신 프레임워크 및 라이브러리 문서 참조 |
10+
| **playwright** | 브라우저 자동화 | E2E 테스트 및 브라우저 테스트 지원 |
11+
| **sequential-thinking** | 복잡한 문제 해결 | 단계별 분석 및 체계적 사고 지원 |
1212

1313
### 설정 방법
1414

‎.github/pull-request-guide.md‎

Lines changed: 0 additions & 45 deletions
This file was deleted.

‎.github/workflows/branch-name-check.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: Branch Name Check
2+
3+
on:
4+
pull_request:
5+
types: [ opened, synchronize, reopened, edited ]
6+
7+
jobs:
8+
validate-branch-name:
9+
runs-on: ubuntu-latest
10+
permissions:
11+
contents: read
12+
steps:
13+
- name: Check branch name
14+
env:
15+
BRANCH: ${{ github.head_ref }}
16+
run: |
17+
echo "Checking branch name: $BRANCH"
18+
19+
# 보호 브랜치는 검사하지 않음
20+
if [[ "$BRANCH" =~ ^(main|master|develop|staging)$ ]]; then
21+
echo "✓ Protected branch - skipping validation"
22+
exit 0
23+
fi
24+
25+
# 허용된 타입
26+
VALID_TYPES="feature|fix|hotfix|release|refactor|docs|test|chore|style|copilot|claude"
27+
28+
# 패턴: type/description 또는 type/domain/description
29+
# 허용: 소문자(a-z), 숫자(0-9), 하이픈(-), 점(.)
30+
PATTERN="^(${VALID_TYPES})/[a-z0-9][a-z0-9.-]*(/[a-z0-9][a-z0-9.-]*)?$"
31+
32+
if [[ ! "$BRANCH" =~ $PATTERN ]]; then
33+
echo "❌ Invalid branch name: $BRANCH"
34+
exit 1
35+
fi
36+
37+
echo "✓ Branch name is valid"

‎.husky/husky-guide.md‎

Lines changed: 52 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,18 @@
88

99
### 허용 타입
1010

11-
| 타입 | 설명 | 예시 |
12-
|------|------|------|
13-
| `feat` | 새로운 기능 추가 | `feat: 사용자 인증 추가` |
14-
| `fix` | 버그 수정 | `fix(api): null 응답 처리` |
15-
| `docs` | 문서 수정 | `docs: 설치 가이드 업데이트` |
16-
| `style` | 코드 스타일 변경 | `style: 코드 포맷팅` |
17-
| `refactor` | 코드 리팩토링 | `refactor(auth): 로직 개선` |
18-
| `test` | 테스트 추가/수정 | `test: 유닛 테스트 추가` |
19-
| `chore` | 빌드/설정 변경 | `chore: 의존성 업데이트` |
20-
| `build` | 빌드 시스템/외부 의존성 변경 | `build: webpack 설정 업데이트` |
21-
| `ci` | CI 설정 파일/스크립트 변경 | `ci: GitHub Actions 워크플로우 추가` |
22-
| `revert` | 이전 커밋 되돌리기 | `revert: feat(auth) 커밋 되돌림` |
11+
| 타입 | 설명 | 예시 |
12+
|------------|------------------|-------------------------------|
13+
| `feat` | 새로운 기능 추가 | `feat: 사용자 인증 추가` |
14+
| `fix` | 버그 수정 | `fix(api): null 응답 처리` |
15+
| `docs` | 문서 수정 | `docs: 설치 가이드 업데이트` |
16+
| `style` | 코드 스타일 변경 | `style: 코드 포맷팅` |
17+
| `refactor` | 코드 리팩토링 | `refactor(auth): 로직 개선` |
18+
| `test` | 테스트 추가/수정 | `test: 유닛 테스트 추가` |
19+
| `chore` | 빌드/설정 변경 | `chore: 의존성 업데이트` |
20+
| `build` | 빌드 시스템/외부 의존성 변경 | `build: webpack 설정 업데이트` |
21+
| `ci` | CI 설정 파일/스크립트 변경 | `ci: GitHub Actions 워크플로우 추가` |
22+
| `revert` | 이전 커밋 되돌리기 | `revert: feat(auth) 커밋 되돌림` |
2323

2424
### 예시
2525

@@ -38,38 +38,59 @@
3838

3939
**실행 시점**: `git push` 시 (푸시 전)
4040
**스크립트**: `validate-branch.cjs`
41-
**형식**: `<type>/<description>`
41+
**형식**: `<type>/<description>` 또는 `<type>/<domain>/<description>`
42+
**허용 문자**: 소문자(a-z), 숫자(0-9), 하이픈(-), 점(.)
4243

4344
### 허용 타입
4445

45-
| 타입 | 설명 | 예시 |
46-
|------|------|------|
47-
| `feature` | 새로운 기능 개발 | `feature/user-authentication` |
48-
| `fix` | 버그 수정 | `fix/login-bug` |
49-
| `hotfix` | 긴급 버그 수정 | `hotfix/critical-security-issue` |
50-
| `release` | 릴리스 준비 | `release/v1.0.0` |
51-
| `refactor` | 코드 리팩토링 | `refactor/auth-logic` |
52-
| `docs` | 문서 업데이트 | `docs/installation-guide` |
53-
| `test` | 테스트 추가 | `test/unit-tests` |
54-
| `chore` | 유지보수 작업 | `chore/update-deps` |
55-
| `style` | 스타일 개선 | `style/format-code` |
56-
| `copilot` | GitHub Copilot 지원 개발 | `copilot/add-validation` |
57-
| `claude` | Claude AI 지원 개발 | `claude/refactor-api` |
46+
| 타입 | 설명 | 예시 |
47+
|------------|----------------------|----------------------------------|
48+
| `feature` | 새로운 기능 개발 | `feature/user-authentication` |
49+
| `fix` | 버그 수정 | `fix/login-bug` |
50+
| `hotfix` | 긴급 버그 수정 | `hotfix/critical-security-issue` |
51+
| `release` | 릴리스 준비 | `release/v1.0.0` |
52+
| `refactor` | 코드 리팩토링 | `refactor/auth-logic` |
53+
| `docs` | 문서 업데이트 | `docs/installation-guide` |
54+
| `test` | 테스트 추가 | `test/unit-tests` |
55+
| `chore` | 유지보수 작업 | `chore/update-deps` |
56+
| `style` | 스타일 개선 | `style/format-code` |
57+
| `copilot` | GitHub Copilot 지원 개발 | `copilot/add-validation` |
58+
| `claude` | Claude AI 지원 개발 | `claude/refactor-api` |
5859

5960
### 보호 브랜치 (직접 푸시 허용)
6061

6162
`main`, `master`, `develop`, `staging`
6263

6364
### 예시
6465

66+
#### 2단계 형식 (기본)
67+
6568
```bash
6669
✅ feature/user-authentication
67-
✅ fix/login-bug
70+
✅ fix/404-error
6871
✅ copilot/add-validation
6972
✅ claude/refactor-api
73+
✅ hotfix/security-patch-2024
74+
✅ release/1.0.0
75+
```
76+
77+
#### 3단계 형식 (도메인 포함)
78+
79+
```bash
80+
✅ feature/frontend/user-authentication
81+
✅ fix/api/null-response
82+
✅ refactor/backend/auth-logic
83+
✅ docs/api/endpoint-guide
84+
✅ test/integration/payment-flow
85+
✅ fix/api/404-error
86+
```
7087

71-
❌ feature_user_auth # 구분자 오류 (/ 사용)
72-
❌ Feature/user-auth # 대문자 사용 금지
73-
❌ feature/User-Auth # 설명에 대문자 사용 금지
74-
❌ my-feature # 타입 누락
88+
#### 잘못된 형식
89+
90+
```bash
91+
❌ Feature/Frontend/User-auth # 타입, 도메인, 설명에 대문자 사용 금지
92+
❌ my-feature # 타입 누락
93+
❌ feature/add_function # 언더스코어 사용 금지
94+
❌ feature/a/b/c # 4단계 이상 금지
95+
❌ feature/ # 설명 누락
7596
```

‎.husky/validate-branch.cjs‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ const {execSync} = require('child_process');
44

55
// 허용 규칙
66
const validTypes = ['feature', 'fix', 'hotfix', 'release', 'refactor', 'docs', 'test', 'chore', 'style', 'copilot', 'claude'];
7-
const validPattern = '<type>/<description>';
7+
const validPattern = '<type>/<description> 또는 <type>/<domain>/<description>';
88

99
// 현재 브랜치명 확인
1010
let currentBranch;
@@ -21,8 +21,9 @@ if (protectedBranches.includes(currentBranch)) {
2121
process.exit(0);
2222
}
2323

24-
// 패턴: `type/description`
25-
const branchPattern = new RegExp(`^(${validTypes.join('|')})\\/[a-z][a-z0-9-]*$`);
24+
// 패턴: `type/description` 또는 `type/domain/description`
25+
// 허용: 소문자(a-z), 숫자(0-9), 하이픈(-), 점(.)
26+
const branchPattern = new RegExp(`^(${validTypes.join('|')})\\/[a-z0-9][a-z0-9.-]*(\\/[a-z0-9][a-z0-9.-]*)?$`);
2627
if (!branchPattern.test(currentBranch)) {
2728
console.error(`* 잘못된 형식 : ${currentBranch}`);
2829
console.error(`* 올바른 형식 : ${validPattern}`);

0 commit comments

Comments
 (0)