From 1934ddff5dff43b5a30996501c61b24e15a7b694 Mon Sep 17 00:00:00 2001
From: yceffort <yc.effort@navercorp.com>
Date: Fri, 1 Aug 2025 15:25:29 +0900
Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=93=9A=20README=20=EC=97=85=EB=8D=B0?=
 =?UTF-8?q?=EC=9D=B4=ED=8A=B8:=20=ED=95=9C=EA=B5=AD=EC=96=B4=20=EB=AC=B8?=
 =?UTF-8?q?=EC=84=9C=20=EC=B6=94=EA=B0=80=20=EB=B0=8F=20=EA=B8=B0=EB=8A=A5?=
 =?UTF-8?q?=20=EC=84=A4=EB=AA=85=20=EB=B3=B4=EA=B0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/commit-helper/README.ko.md | 212 +++++++++++++++++++++++++++
 packages/commit-helper/README.md    | 218 ++++++++++++++++++++++------
 2 files changed, 383 insertions(+), 47 deletions(-)
 create mode 100644 packages/commit-helper/README.ko.md

diff --git a/packages/commit-helper/README.ko.md b/packages/commit-helper/README.ko.md
new file mode 100644
index 0000000..8ddd5a4
--- /dev/null
+++ b/packages/commit-helper/README.ko.md
@@ -0,0 +1,212 @@
+# @naverpay/commit-helper
+
+> 브랜치 이름을 기반으로 커밋 메시지에 이슈 번호를 자동으로 추가하고 중요 브랜치를 보호하는 도구
+
+## 설치
+
+```bash
+npm install --save-dev @naverpay/commit-helper
+# or
+yarn add -D @naverpay/commit-helper
+# or
+pnpm add -D @naverpay/commit-helper
+```
+
+## 빠른 시작
+
+### 1. Husky 설치 (아직 설치하지 않은 경우)
+
+```bash
+npm install --save-dev husky
+npx husky init
+```
+
+### 2. commit-msg 훅 추가
+
+```bash
+echo 'npx --yes @naverpay/commit-helper@latest $1' > .husky/commit-msg
+chmod +x .husky/commit-msg
+```
+
+### 3. 커밋 생성
+
+```bash
+git checkout -b feature/123-new-feature
+git add .
+git commit -m "새로운 기능 추가"
+# 결과: [#123] 새로운 기능 추가
+```
+
+## 주요 기능
+
+### 🏷️ 자동 이슈 태깅
+
+브랜치 이름에서 이슈 번호를 추출하여 커밋 메시지에 추가:
+
+- `feature/123` → `[#123] 메시지`
+- `qa/456` → `[your-org/your-repo#456] 메시지`
+- `hotfix/789-urgent` → `[#789] 메시지`
+
+### 🛡️ 브랜치 보호
+
+보호된 브랜치에 직접 커밋 방지:
+
+- 기본값: `main`, `master`, `develop`
+- 설정으로 커스터마이징 가능
+
+### ⚙️ 유연한 설정
+
+커스텀 규칙과 원격 설정 상속을 지원합니다.
+
+## 설정
+
+프로젝트 루트에 `.commithelperrc.json` 파일 생성:
+
+```json
+{
+    "protect": ["main", "master", "develop", "staging"],
+    "rules": {
+        "feature": null,
+        "bugfix": null,
+        "hotfix": null,
+        "qa": "naverpay/qa-issues",
+        "docs": "naverpay/documentation"
+    }
+}
+```
+
+### 설정 옵션
+
+#### `protect` (배열)
+
+직접 커밋을 차단할 브랜치 이름 목록
+
+- 기본값: `["main", "master", "develop"]`
+
+#### `rules` (객체)
+
+브랜치 접두사와 저장소 이름의 매핑
+
+- 키: 브랜치 접두사 (예: `"feature"`)
+- 값: 저장소 이름 또는 현재 저장소인 경우 `null`
+
+#### `extends` (문자열)
+
+설정을 상속받을 URL:
+
+```json
+{
+    "extends": "https://raw.githubusercontent.com/naverpay/standards/main/.commithelperrc.json"
+}
+```
+
+## 예제
+
+### 기본 기능 브랜치
+
+```bash
+git checkout -b feature/NP-1234-결제-통합
+git commit -m "결제 게이트웨이 구현"
+# 결과: [#1234] 결제 게이트웨이 구현
+```
+
+### 외부 저장소 참조
+
+설정 파일:
+
+```json
+{
+    "rules": {
+        "qa": "naverpay/qa-tracker"
+    }
+}
+```
+
+```bash
+git checkout -b qa/789-결제-플로우-테스트
+git commit -m "결제 E2E 테스트 추가"
+# 결과: [naverpay/qa-tracker#789] 결제 E2E 테스트 추가
+```
+
+### 보호된 브랜치
+
+```bash
+git checkout main
+git commit -m "직접 커밋"
+# 오류: ❌ 보호된 브랜치 'main'에 직접 커밋할 수 없습니다!
+# 기능 브랜치를 생성하고 풀 리퀘스트를 사용하세요.
+```
+
+## 고급 사용법
+
+### Lefthook 연동
+
+Husky 대신 Lefthook을 선호하는 경우:
+
+```yaml
+# lefthook.yml
+commit-msg:
+    scripts:
+        'commit-helper':
+            runner: npx --yes @naverpay/commit-helper@latest {1}
+```
+
+### CI/CD 연동
+
+CI에서 커밋 메시지 검증:
+
+```yaml
+# .github/workflows/pr.yml
+- name: 커밋 메시지 검증
+  run: |
+      git log --format=%s origin/main..HEAD | while read msg; do
+        if ! echo "$msg" | grep -qE '^\[[#A-Za-z0-9-/]+\]'; then
+          echo "잘못된 커밋 메시지: $msg"
+          exit 1
+        fi
+      done
+```
+
+## API
+
+### CLI 사용법
+
+```bash
+npx @naverpay/commit-helper <commit-msg-file>
+```
+
+- **매개변수**:
+  - `commit-msg-file` (문자열): 커밋 메시지 파일 경로 (git hook이 제공)
+- **반환값**: 성공 시 종료 코드 0, 실패 시 1
+- **에러**: 잘못된 설정이나 보호된 브랜치인 경우 stderr로 에러 메시지 출력
+
+## 자주 묻는 질문
+
+**Q: 이미 이슈 태그가 있는 경우에도 작동하나요?**  
+A: 네, 커밋 메시지에 이미 `[#123]` 같은 태그가 있으면 commit-helper는 건너뜁니다.
+
+**Q: 여러 이슈 번호를 사용할 수 있나요?**  
+A: 브랜치 이름에서는 하나의 이슈 번호만 지원하지만, 커밋 메시지에 수동으로 추가할 수 있습니다.
+
+**Q: 어떤 브랜치 이름 형식을 지원하나요?**  
+A: 슬래시 뒤에 숫자가 있는 모든 형식: `feature/123`, `feature/123-설명`, `feature/123_설명`
+
+**Q: 일시적으로 보호를 우회하려면?**  
+A: `--no-verify` 플래그 사용: `git commit --no-verify -m "긴급 수정"`
+
+## 문제 해결
+
+### 훅이 실행되지 않음
+
+1. 파일 권한 확인: `ls -la .husky/commit-msg`
+2. Husky 설치 확인: `npx husky install`
+
+### 설정이 로드되지 않음
+
+1. 파일 이름 확인: `.commithelperrc.json` (점으로 시작)
+2. JSON 문법 검증
+3. 디버그 모드 실행: `DEBUG=commit-helper git commit`
+
+## 라이선스
+
+MIT
diff --git a/packages/commit-helper/README.md b/packages/commit-helper/README.md
index 6a67f19..1c4f858 100644
--- a/packages/commit-helper/README.md
+++ b/packages/commit-helper/README.md
@@ -1,89 +1,213 @@
 # @naverpay/commit-helper
 
-This CLI provides various tools which assist your commit based on [husky](https://typicode.github.io/husky/) `commit-msg` hook.
+> Automatically adds issue numbers to commit messages based on branch names and protects important branches
 
-## How to use
+## Installation
 
-### .husky/commit-msg
+```bash
+npm install --save-dev @naverpay/commit-helper
+# or
+yarn add -D @naverpay/commit-helper
+# or
+pnpm add -D @naverpay/commit-helper
+```
+
+## Quick Start
 
+### 1. Install Husky (if not already installed)
+
+```bash
+npm install --save-dev husky
+npx husky init
 ```
-npx --yes @naverpay/commit-helper@latest $1
+
+### 2. Add commit-msg hook
+
+```bash
+echo 'npx --yes @naverpay/commit-helper@latest $1' > .husky/commit-msg
+chmod +x .husky/commit-msg
 ```
 
-> `@latest` is not necessary but this option always provides latest version of commit-helper.
+### 3. Create a commit
 
-## what it does
+```bash
+git checkout -b feature/123-new-feature
+git add .
+git commit -m "Add new feature"
+# Result: [#123] Add new feature
+```
 
-### Tag related issue
+## Features
 
-> Automatically Add your related github issue number at your commit message through your branch name
+### 🏷️ Automatic Issue Tagging
 
-```shell
-➜  your-repo git:(feature/1) git add . &&  git commit -m ":memo: test"
-ℹ No staged files match any configured task.
-$ git branch --show-current
-feature/1
-[feature/1 1e70c244f] [#1] :memo: test
- 1 file changed, 1 insertion(+)
-```
+Extracts issue numbers from branch names and adds them to commit messages:
 
-Your issue number is automatically tagged base on your setting (`.commithelperrc.json`)
+- `feature/123` → `[#123] your message`
+- `qa/456` → `[your-org/your-repo#456] your message`
+- `hotfix/789-urgent` → `[#789] your message`
 
-### Blocking commit
+### 🛡️ Branch Protection
 
-- Blocks direct commit toward `main`, `develop` `master` branch by throwing error on commit attempt.
-- To block specific branches, add at `protect` field on `commithelperrc`.
+Prevents direct commits to protected branches:
 
-#### Customization
+- Default: `main`, `master`, `develop`
+- Customizable via configuration
 
-If you need to add customized commit rule, use [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) rules as `commithelper`. `cosmiconfig` is a library widely used in tools like `eslint` and `prettier` to read `rc` configuration files. `commithelper` also uses `cosmiconfig`. If there is any conflict with predefined rules, `cosmicconfig` takes precedence.
+### ⚙️ Flexible Configuration
 
-### commithelperrc
+Supports custom rules and remote configuration inheritance.
 
-This is Basic rule of `.commithelperrc`.
+## Configuration
+
+Create `.commithelperrc.json` in your project root:
 
 ```json
 {
-    "protect": ["main", "master", "develop"],
+    "protect": ["main", "master", "develop", "staging"],
     "rules": {
         "feature": null,
-        "qa": "your-org/your-repo"
+        "bugfix": null,
+        "hotfix": null,
+        "qa": "naverpay/qa-issues",
+        "docs": "naverpay/documentation"
     }
 }
 ```
 
-#### rules
+### Configuration Options
+
+#### `protect` (array)
+
+List of branch names to protect from direct commits.
+
+- Default: `["main", "master", "develop"]`
+
+#### `rules` (object)
+
+Mapping of branch prefixes to repository names.
+
+- Key: Branch prefix (e.g., `"feature"`)
+- Value: Repository name or `null` for current repo
+
+#### `extends` (string)
+
+URL to inherit configuration from:
+
+```json
+{
+    "extends": "https://raw.githubusercontent.com/naverpay/standards/main/.commithelperrc.json"
+}
+```
+
+## Examples
 
-- Key of rules field means branch prefix. By `feature` key, this rule is applied to branches named using the `feature/***` pattern.
-- Value represents the repository to be tagged. For example, rule with value 'your-org/your-repo' tags 'your-org/your-repo#1'.
-- A rule with a `null` value tags repository itself.
+### Basic Feature Branch
 
-#### protect
+```bash
+git checkout -b feature/NP-1234-payment-integration
+git commit -m "Implement payment gateway"
+# Result: [#1234] Implement payment gateway
+```
 
-- Defines branch prefixes that are blocked from committing. `main`, `master`, `develop` branch is blocked by default.
+### External Repository Reference
 
-### Example
+With configuration:
 
 ```json
-// commithelperrc.json
 {
-    "protect": ["epic"],
     "rules": {
-        "feature": null,
-        "qa": "your-org/your-repo"
+        "qa": "naverpay/qa-tracker"
     }
 }
 ```
 
-> For example as above,
->
-> - commit on `feature/1` branch will be tagged as `[#1]`.
-> - commit on `qa/1` branch will be tagged as `[your-org/your-repo#1]`.
-> - direct commit attempt toward `main`, `master`, `develop`, `epic/***` branch will be blocked
+```bash
+git checkout -b qa/789-test-payment-flow
+git commit -m "Add E2E tests for payment"
+# Result: [naverpay/qa-tracker#789] Add E2E tests for payment
+```
+
+### Protected Branch
+
+```bash
+git checkout main
+git commit -m "Direct commit"
+# Error: ❌ Direct commits to protected branch 'main' are not allowed!
+# Please create a feature branch and use pull request.
+```
+
+## Advanced Usage
+
+### Lefthook Integration
+
+If you prefer Lefthook over Husky:
+
+```yaml
+# lefthook.yml
+commit-msg:
+    scripts:
+        'commit-helper':
+            runner: npx --yes @naverpay/commit-helper@latest {1}
+```
+
+### CI/CD Integration
+
+For commit message validation in CI:
+
+```yaml
+# .github/workflows/pr.yml
+- name: Validate commit messages
+  run: |
+      git log --format=%s origin/main..HEAD | while read msg; do
+        if ! echo "$msg" | grep -qE '^\[[#A-Za-z0-9-/]+\]'; then
+          echo "Invalid commit message: $msg"
+          exit 1
+        fi
+      done
+```
+
+## API
+
+### CLI Usage
+
+```bash
+npx @naverpay/commit-helper <commit-msg-file>
+```
+
+- **Parameters**:
+  - `commit-msg-file` (string): Path to commit message file (provided by git hook)
+- **Returns**: Exit code 0 on success, 1 on failure
+- **Throws**: Error message to stderr on invalid configuration or protected branch
+
+## FAQ
+
+**Q: Does it work with existing issue tags?**  
+A: Yes, if your commit message already contains a tag like `[#123]`, commit-helper will skip it.
+
+**Q: Can I use multiple issue numbers?**  
+A: The branch name supports one issue number, but you can manually add more in your commit message.
+
+**Q: What branch name formats are supported?**  
+A: Any format with a number after slash: `feature/123`, `feature/123-description`, `feature/123_description`
+
+**Q: How to temporarily bypass protection?**  
+A: Use `--no-verify` flag: `git commit --no-verify -m "Emergency fix"`
+
+## Troubleshooting
+
+### Hook not executing
+
+1. Check file permissions: `ls -la .husky/commit-msg`
+2. Ensure Husky is installed: `npx husky install`
+
+### Configuration not loading
+
+1. Check file name: `.commithelperrc.json` (note the dot)
+2. Validate JSON syntax
+3. Run with debug: `DEBUG=commit-helper git commit`
 
-## Q&A
+## License
 
-- What happens if commit has already tagged issue like `[your-org/your-repo#1]`?
-  - `commithelper` do not works. Already tagged issue remains unchanged
-- How does commit-helper behaves on `feature/1_xxx` `feature/1-xxx` patterned branch name?
-  - It works same as `feature/1` branch.
+MIT
+No newline at end of file

From f72604a38a416fb5f33b049043967c5133b02054 Mon Sep 17 00:00:00 2001
From: yceffort <yc.effort@navercorp.com>
Date: Fri, 1 Aug 2025 15:28:03 +0900
Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=94=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/commit-helper/README.ko.md | 1 -
 packages/commit-helper/README.md    | 1 -
 2 files changed, 2 deletions(-)

diff --git a/packages/commit-helper/README.ko.md b/packages/commit-helper/README.ko.md
index 8ddd5a4..42f9f73 100644
--- a/packages/commit-helper/README.ko.md
+++ b/packages/commit-helper/README.ko.md
@@ -205,7 +205,6 @@ A: `--no-verify` 플래그 사용: `git commit --no-verify -m "긴급 수정"`
 
 1. 파일 이름 확인: `.commithelperrc.json` (점으로 시작)
 2. JSON 문법 검증
-3. 디버그 모드 실행: `DEBUG=commit-helper git commit`
 
 ## 라이선스
 
diff --git a/packages/commit-helper/README.md b/packages/commit-helper/README.md
index 1c4f858..dc21cae 100644
--- a/packages/commit-helper/README.md
+++ b/packages/commit-helper/README.md
@@ -205,7 +205,6 @@ A: Use `--no-verify` flag: `git commit --no-verify -m "Emergency fix"`
 
 1. Check file name: `.commithelperrc.json` (note the dot)
 2. Validate JSON syntax
-3. Run with debug: `DEBUG=commit-helper git commit`
 
 ## License
 

From 50355c4a93586fd1321e4bfa8d9e95062a02dc08 Mon Sep 17 00:00:00 2001
From: yceffort <yc.effort@navercorp.com>
Date: Fri, 1 Aug 2025 15:30:22 +0900
Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=9B=A0=EF=B8=8F=20=EC=83=81=EC=88=98?=
 =?UTF-8?q?=20=EC=88=98=EC=A0=95:=20DEFAULT=5FPROTECTED=5FBRANCHES?=
 =?UTF-8?q?=EC=97=90=EC=84=9C=20'master'=EC=99=80=20'develop'=20=EC=A0=9C?=
 =?UTF-8?q?=EA=B1=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/commit-helper/src/constant.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/commit-helper/src/constant.ts b/packages/commit-helper/src/constant.ts
index 84fb918..ef7ddc7 100644
--- a/packages/commit-helper/src/constant.ts
+++ b/packages/commit-helper/src/constant.ts
@@ -2,7 +2,8 @@ export const ISSUE_TAGGING_MAP = {
     repo: null,
     feature: null,
 } as const
+
 export const ISSUE_TAGGING_REGEX = /\[(?:[A-Za-z-_]+\/)?[A-Za-z-_]*#\d{1,5}\]/
 export const BRANCH_ISSUE_TAGGING_REGEX = /[A-Za-z-]+\/\d{1,5}([-_a-zA-Z]+[0-9]*)*$/
 export const PURE_BRANCH_ISSUE_TAGGING_REGEX = /[A-Za-z-]+\/\d{1,5}/
-export const DEFAULT_PROTECTED_BRANCHES: Readonly<string[]> = ['main', 'master', 'develop']
+export const DEFAULT_PROTECTED_BRANCHES: Readonly<string[]> = ['main']

From 90d2cbf7b2ca0c4129896c5cb2deed76b9af288f Mon Sep 17 00:00:00 2001
From: yceffort_naver <158988311+yceffort-naver@users.noreply.github.com>
Date: Fri, 1 Aug 2025 15:31:27 +0900
Subject: [PATCH 4/4] Create blue-zebras-bake.md

---
 .changeset/blue-zebras-bake.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 .changeset/blue-zebras-bake.md

diff --git a/.changeset/blue-zebras-bake.md b/.changeset/blue-zebras-bake.md
new file mode 100644
index 0000000..c2e6c30
--- /dev/null
+++ b/.changeset/blue-zebras-bake.md
@@ -0,0 +1,7 @@
+---
+"@naverpay/commit-helper": patch
+---
+
+🔥 remove 'develop' 'master' branch rules from DEFAULT_PROTECTED_BRANCHES
+
+PR: [📚 README 업데이트: 한국어 문서 추가 및 기능 설명 보강](https://github.com/NaverPayDev/cli/pull/46)