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) diff --git a/packages/commit-helper/README.ko.md b/packages/commit-helper/README.ko.md new file mode 100644 index 0000000..42f9f73 --- /dev/null +++ b/packages/commit-helper/README.ko.md @@ -0,0 +1,211 @@ +# @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` (๋ฌธ์ž์—ด): ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€ ํŒŒ์ผ ๊ฒฝ๋กœ (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 ๋ฌธ๋ฒ• ๊ฒ€์ฆ + +## ๋ผ์ด์„ ์Šค + +MIT diff --git a/packages/commit-helper/README.md b/packages/commit-helper/README.md index 6a67f19..dc21cae 100644 --- a/packages/commit-helper/README.md +++ b/packages/commit-helper/README.md @@ -1,89 +1,212 @@ # @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 +``` + +- **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 -## 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 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 = ['main', 'master', 'develop'] +export const DEFAULT_PROTECTED_BRANCHES: Readonly = ['main']