From 7358cd0123fe3bcd2f1e25e08cb14870ec9bfe8e Mon Sep 17 00:00:00 2001
From: huangjianwu <huangjianwu@ynyuc.com>
Date: Thu, 7 May 2026 14:19:39 +0800
Subject: [PATCH] =?UTF-8?q?fix(ci):=20commitlint=20workflow=20=E5=8E=BB?=
 =?UTF-8?q?=E6=8E=89=E4=BC=AA=20input=20+=20=E8=A7=84=E8=8C=83=20release?=
 =?UTF-8?q?=20merge=20commit=20=E6=A0=BC=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

v2.1.3 push master 时 Lint commit messages job 红了，根因两条：

1. workflow 里写了 'firstParent: false'，但 wagoid/commitlint-github-action@v6
   的合法 input 列表里没这个字段，被 ignore 同时打 warn

2. release merge commit 标题 'Release v2.1.3' 不符合 type(scope): subject 格式，
   commitlint 报 subject-empty + type-empty
   · @commitlint/config-conventional 默认 ignore 'Merge ' 前缀的 commit，
     但我们手动 -m 把标题写成 'Release vX.Y.Z' 跳过了豁免

修：
- 去掉 .github/workflows/commitlint.yml 里那条 firstParent 假 input
- RELEASING.md §3 加入 merge commit 标题模板：
  · 合 master 用 'chore(release): vX.Y.Z'
  · 回灌 develop 用 'chore(release): merge release/X.Y.Z back into develop'
- CONTRIBUTING.md §6.3 同步加这条提醒

历史上 master / develop 的 'Release v2.1.x' 那几个 merge commit 已经在 history
里，没法回头改（不能强推 master）。但 commitlint 在 push 时只 lint 推送范围里的
新 commit，旧 commit 不会重新校验，所以不会持续报错。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/commitlint.yml |  2 --
 CONTRIBUTING.md                  |  1 +
 RELEASING.md                     | 11 +++++++----
 3 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/commitlint.yml b/.github/workflows/commitlint.yml
index 8ae2aa6..fff8ca2 100644
--- a/.github/workflows/commitlint.yml
+++ b/.github/workflows/commitlint.yml
@@ -26,7 +26,5 @@ jobs:
         uses: wagoid/commitlint-github-action@v6
         with:
           configFile: .commitlintrc.json
-          # PR 上检查 base..head 之间所有 commit；push 上只校验最新 commit
-          firstParent: false
           failOnWarnings: false
           helpURL: https://github.com/JefferyHcool/BiliNote/blob/develop/CONTRIBUTING.md#5-提交规范
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5085696..5f95d0b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -250,6 +250,7 @@ chore(ci): 优化 docker 构建缓存
 
 - `feature/*` / `fix/*` 合入 `develop`：推荐 **Squash and merge**，保持 develop 历史线性。
 - `release/*` 合入 `master` 与回灌 `develop`：使用 **Merge commit (--no-ff)**，保留发版结构。
+  · merge commit 标题用 `chore(release): vX.Y.Z`（合 master）或 `chore(release): merge release/X.Y.Z back into develop`（回灌 develop），保证 commitlint 通过。
 - `hotfix/*` 同上 release。
 
 ### 6.4 合并后
diff --git a/RELEASING.md b/RELEASING.md
index 8a46202..ad47892 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -42,10 +42,13 @@ git push -u origin release/X.Y.Z
 
 在 GitHub 上发起两个 PR：
 
-| PR | base | 合并方式 |
-|---|---|---|
-| `release/X.Y.Z` → `master` | `master` | **Merge commit (--no-ff)** |
-| `release/X.Y.Z` → `develop` | `develop` | **Merge commit (--no-ff)** |
+| PR | base | 合并方式 | 合并后 commit 标题 |
+|---|---|---|---|
+| `release/X.Y.Z` → `master` | `master` | **Merge commit (--no-ff)** | `chore(release): vX.Y.Z` |
+| `release/X.Y.Z` → `develop` | `develop` | **Merge commit (--no-ff)** | `chore(release): merge release/X.Y.Z back into develop` |
+
+> ⚠️ Merge commit 的标题**必须**符合 `type(scope): subject` 格式（commitlint 在 push 到 master/develop 时会校验）。
+> 历史上用过 `Release vX.Y.Z` 这种形式，会被 commitlint 报 `type-empty` / `subject-empty`。
 
 `master` 分支保护要求 review 通过。回灌 `develop` 是为了把发版冻结期内的小修同步回来。