chore(repo): enforce conventional commits

.github/workflows/commitlint.yml

@@ -0,0 +1,53 @@
+name: Commit Lint
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  commitlint:
+    name: Validate Commit Messages
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint commit messages
+        shell: bash
+        run: |
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            FROM="${{ github.event.pull_request.base.sha }}"
+            TO="${{ github.event.pull_request.head.sha }}"
+          else
+            FROM="${{ github.event.before }}"
+            TO="${{ github.sha }}"
+          fi
+
+          if [[ "$FROM" == "0000000000000000000000000000000000000000" ]]; then
+            npx commitlint --last --verbose
+          else
+            npx commitlint --from "$FROM" --to "$TO" --verbose
+          fi

CLAUDE.md

@@ -31,8 +31,16 @@ npm run lint:fix         # Fix linting issues
 npm run format           # Format code with Prettier
 npm run format:check     # Check formatting without changes
 npm run type-check       # TypeScript type checking (no emit)
+npm run commitlint       # Validate the latest commit message
 ```
 
+## Commit Messages
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for every commit
+- Preferred format: `type(scope): description`
+- Common types: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `chore`
+- The repository installs a `commit-msg` hook via `npm install`; do not bypass it unless explicitly required
+
 ### Testing Workflow
 
 - Tests use Vitest with `@cloudflare/vitest-pool-workers` for Workers-specific testing

CONTRIBUTING.md

@@ -14,7 +14,8 @@
 
 - fork 存储库到您的 GitHub 账户
 - 创建功能分支 (`git checkout -b feature/amazing-feature`)
-- 提交更改 (`git commit -m 'Add some amazing feature'`)
+- 安装依赖以启用本地 Git hooks (`npm install`)
+- 使用 Conventional Commits 提交更改 (`git commit -m 'feat(platforms): add amazing feature'`)
 - 推送到分支 (`git push origin feature/amazing-feature`)
 - 创建 Pull Request
 
@@ -44,6 +45,8 @@ cd Xget
 # 安装依赖
 npm install
 
+# 安装后会自动启用 commit-msg hook
+
 # 启动开发服务器
 npm run dev
 
@@ -149,6 +152,11 @@ docs(readme): update installation instructions
 perf(proxy): optimize request handling performance
 ```
 
+### 自动校验
+
+- `npm install` 会自动安装 `commit-msg` hook，在本地阻止不符合规范的提交
+- GitHub Actions 会在 `push` 和 `pull_request` 中再次校验提交消息，防止绕过本地 hook
+
 ## 🔍 Pull Request 流程
 
 ### 提交前检查

commitlint.config.mjs

@@ -0,0 +1,3 @@
+export default {
+  extends: ["@commitlint/config-conventional"],
+};

package.json

@@ -4,6 +4,8 @@
     "xget": "file:"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
     "@cloudflare/vitest-pool-workers": "^0.12.18",
     "@cloudflare/workers-types": "^4.20260303.0",
     "@eslint/js": "^9.39.3",
@@ -11,6 +13,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsdoc": "^62.7.1",
     "prettier": "^3.8.1",
+    "simple-git-hooks": "^2.13.1",
     "typescript": "^5.9.3",
     "vitest": "^3.1.4",
     "wrangler": "^4.69.0"
@@ -18,12 +21,15 @@
   "name": "xget",
   "private": false,
   "scripts": {
+    "commitlint": "commitlint --last --verbose",
+    "commitmsg": "commitlint --edit",
     "deploy": "wrangler deploy",
     "dev": "wrangler dev",
     "format": "prettier --write src/ test/ *.js *.json",
     "format:check": "prettier --check src/ test/ *.js *.json",
     "lint": "eslint src/ test/ adapters/",
     "lint:fix": "eslint src/ test/ adapters/ --fix",
+    "prepare": "simple-git-hooks",
     "start": "wrangler dev",
     "test": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -32,6 +38,9 @@
     "test:watch": "vitest --watch",
     "type-check": "tsc --noEmit"
   },
+  "simple-git-hooks": {
+    "commit-msg": "npx commitlint --edit $1"
+  },
   "type": "module",
   "version": "1.0.0"
 }