chore(repo): 仓库工具链——issue/PR 模板 + commitlint CI + 插件发版工作流

把 CONTRIBUTING.md 里写的规范落到 GitHub 工程化层。 Issue / PR 模板： - .github/ISSUE_TEMPLATE/{config,bug_report,feature_request}.yml · yml 表单形式，跟随当前工作区分类（backend / frontend / extension / Tauri） · bug_report 强制选版本 + 部署方式 + 复现步骤；提交前自查不夹带 secrets · config.yml 禁用空白 issue，引导 Discussions - .github/pull_request_template.md：把 CONTRIBUTING §5.2 的 PR 正文要求落成 checklist - 删旧版 .md 模板（含中文文件名那条），避免新老两套并存 Commitlint： - .commitlintrc.json：extend conventional + 自定义 type 白名单（feat/fix/docs/style/refactor/perf/test/build/ci/chore/ui/revert） - .github/workflows/commitlint.yml：用 wagoid/commitlint-github-action@v6，PR + push develop/master 时校验 · subject-case / subject-full-stop 关掉，兼容中文 subject · header-max-length 100 字符 warn 级别，不阻塞合并插件发版工作流： - .github/workflows/release-extension.yml：v* tag push 时 · cd BillNote_extension && pnpm install + build · pack:zip / pack:xpi / pack:crx（crx 缺 key 自动跳过） · 产物重命名带版本后缀，挂到对应 GitHub Release - 末尾保留 publish-chrome / publish-edge / publish-firefox 三段注释，配齐 secrets 即可启用商店自动发布 - RELEASING.md：发版执行手册，覆盖 release/* 流程 + 各商店人工上传步骤 + 自动发布所需 secrets CONTRIBUTING.md 关联文档区指到新增的 RELEASING.md，commit 章节加 commitlint 落地说明。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 11:30:44 +08:00 · 2026-05-07 13:45:32 +08:00
parent 3d0838ba72
commit b2af0e4e53
11 changed files with 517 additions and 78 deletions
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,49 +0,0 @@
---
-name: Bug report
-about: 上报一些bug
-title: "[BUG]"
-labels: bug
-assignees: JefferyHcool
-
---
-
---
-name: 🐛 Bug 反馈
-about: 提交一个 Bug 报告，帮助我们改进
-title: "[Bug] "
-labels: bug
-assignees: ''
---
-
-**版本说明**
-
-请说明的你的版本号
-
-**部署方式**
-
-使用的是什么方式部署（代码环境部署，docker部署，桌面端，在线预览）
-
-**描述问题**
-清晰、简明地描述你遇到的问题是什么。
-
-**复现步骤**
-复现该问题的步骤：
-
-1. 进入页面 '...'
-2. 点击 '...'
-3. 滚动到 '...'
-4. 出现错误
-
-**预期行为**
-清晰、简明地描述你本来预期发生的行为。
-
-**截图**
-如果适用，请添加截图以帮助说明问题。
-
-**桌面端（请补充以下信息）**
-
- - 操作系统：例如 Windows / macOS / Ubuntu
- - 浏览器：例如 Chrome、Safari
-
-**其他补充信息**
-请补充任何其他相关信息。
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,93 @@
+name: 🐛 Bug 报告
+description: 报告一个可复现的问题
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        感谢反馈。请尽量提供完整的复现路径与日志，便于排查。
+        ⚠️ **不要**贴 API key、SESSDATA、密钥等敏感信息。
+  - type: dropdown
+    id: workspace
+    attributes:
+      label: 受影响的工作区
+      multiple: true
+      options:
+        - 后端 (backend/)
+        - Web 前端 (BillNote_frontend/)
+        - 浏览器插件 (BillNote_extension/)
+        - Tauri 桌面端
+        - 文档 / 其他
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: 版本
+      description: BiliNote 版本号（README 顶部，例如 v2.1.0）
+      placeholder: v2.1.0
+    validations:
+      required: true
+  - type: dropdown
+    id: deploy
+    attributes:
+      label: 部署方式
+      options:
+        - 源码运行
+        - Docker (docker-compose.yml)
+        - Docker GPU (docker-compose.gpu.yml)
+        - 桌面端安装包 (Tauri Release)
+        - 其他
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: 复现步骤
+      description: 一步步说明如何触发问题
+      placeholder: |
+        1. 打开 ...
+        2. 点击 ...
+        3. 看到 ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 期望行为
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: 实际行为
+      description: 含错误信息、截图、录屏均可
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: 运行环境
+      description: 操作系统、Python 版本、Node 版本、浏览器（如适用）
+      placeholder: |
+        - OS: macOS 14.5 / Windows 11 / Ubuntu 22.04
+        - Python: 3.11.6
+        - Node: 20.18.0
+        - Browser: Chrome 124（如涉及插件/前端）
+        - GPU: 无 / NVIDIA 4070（如涉及 fast-whisper / video understanding）
+  - type: textarea
+    id: logs
+    attributes:
+      label: 日志 / 堆栈
+      description: 后端 console、前端 DevTools、扩展 background 页都可以贴
+      render: text
+  - type: checkboxes
+    id: pre-checks
+    attributes:
+      label: 提交前自查
+      options:
+        - label: 我已搜索过 [Issues](https://github.com/JefferyHcool/BiliNote/issues?q=)，确认不是重复问题
+          required: true
+        - label: 我提供的日志中**不**包含 API key、cookie、SESSDATA 等敏感信息
+          required: true
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 📖 文档与常见问题
+    url: https://docs.bilinote.app/
+    about: 安装与配置遇到问题，先看一下文档
+  - name: 💬 提问 / 讨论
+    url: https://github.com/JefferyHcool/BiliNote/discussions
+    about: 用法咨询、想法征集请发到 Discussions（不是 bug 才用 Issues）
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,40 @@
+name: ✨ 功能建议
+description: 提议新功能或改进
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: 想解决什么问题？
+      description: 描述你遇到的实际场景或痛点。
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: 建议方案
+      description: 期望的功能或交互。可附草图 / 示例。
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: 备选方案
+      description: 你考虑过哪些其他做法？为什么没采用？
+  - type: dropdown
+    id: workspace
+    attributes:
+      label: 涉及的工作区
+      multiple: true
+      options:
+        - 后端 (backend/)
+        - Web 前端 (BillNote_frontend/)
+        - 浏览器插件 (BillNote_extension/)
+        - Tauri 桌面端
+        - 不确定
+  - type: textarea
+    id: extra
+    attributes:
+      label: 其他补充
+      description: 关联 issue、参考资料、产品截图等
--- a/.github/ISSUE_TEMPLATE/新增功能建议.md
+++ b/.github/ISSUE_TEMPLATE/新增功能建议.md
@@ -1,29 +0,0 @@
---
-name: 新增功能建议
-about: 一些新的功能建议
-title: "[FEATHURE]"
-labels: enhancement
-assignees: JefferyHcool
-
---
-
---
-name: ✨ 功能请求
-about: 提出一个新的功能建议
-title: "[Feature] "
-labels: enhancement
-assignees: ''
-
---
-
-**这个功能请求是否与某个问题相关？请描述**
-清晰简要地描述问题是什么。例如：每次遇到 [...] 都让我感到很沮丧。
-
-**描述你希望实现的解决方案**
-清晰简要地描述你希望发生的事情。
-
-**描述你考虑过的备选方案**
-清晰简要地描述你考虑过的其他解决方案或功能。
-
-**其他补充信息**
-请在此添加关于功能请求的其他上下文或截图。
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -0,0 +1,39 @@
+<!--
+PR 标题请遵循 type(scope): subject 格式，例如：
+  feat(extension): 侧边栏接入思维导图
+  fix(bilibili): 修正字幕优先链路在未登录态下的回退
+分支命名 / 提交规范见 CONTRIBUTING.md。
+-->
+
+## 改动概述
+
+<!-- 一句话说清这个 PR 做了什么 -->
+
+## 为什么
+
+<!-- 背景、关联 issue（Fixes #xxx / Refs #xxx）、用户场景 -->
+
+## 做了什么
+
+<!-- 关键文件、关键决策。可贴关键片段或截图 -->
+
+## 测试方式
+
+- [ ] `pnpm typecheck && pnpm build`（前端 / 插件）通过
+- [ ] `python -m py_compile <文件>` 或本地 backend 启动验证（后端）通过
+- [ ] 手动验证步骤：
+  <!-- 描述如何复现验证；UI 改动请附截图 / 录屏 -->
+
+## 回归风险
+
+<!-- 影响面、可能受波及的功能、是否需要前后端 / 配置 同步部署 -->
+
+## Checklist
+
+- [ ] 分支命名遵循 [CONTRIBUTING.md §3](../CONTRIBUTING.md#3-分支命名)（`feature/*` / `fix/*` / `release/*` / `hotfix/*`）
+- [ ] base 分支正确（常规改动 → `develop`；线上紧急 → `master`；发版 → 见 §4.3）
+- [ ] Commit message 遵循 `type(scope): subject` 格式（[CONTRIBUTING.md §5.1](../CONTRIBUTING.md#51-commit-message-格式)）
+- [ ] 已自测核心流程
+- [ ] 已更新相关文档（`README.md` / `CHANGELOG.md` / `CLAUDE.md` / 模块 README，如适用）
+- [ ] 未夹带 secrets / `.env` / 大型二进制
+- [ ] 单 PR 不跨多个工作区做无关改动
--- a/.github/workflows/commitlint.yml
+++ b/.github/workflows/commitlint.yml
@@ -0,0 +1,32 @@
+name: Commit Lint
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  push:
+    branches:
+      - develop
+      - master
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  commitlint:
+    name: Lint commit messages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run commitlint
+        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-提交规范
--- a/.github/workflows/release-extension.yml
+++ b/.github/workflows/release-extension.yml
@@ -0,0 +1,115 @@
+name: Release Extension
+
+# 在 v* tag push 时触发，构建插件并把产物挂到对应 GitHub Release。
+# 商店上传仍走人工（详见 RELEASING.md）；如果将来配齐了商店 API secrets，
+# 把本文件末尾注释的 publish-* job 解开就是自动发布。
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build & attach to release
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: BillNote_extension
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 9
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          cache-dependency-path: BillNote_extension/pnpm-lock.yaml
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Pack zip (Chrome / Edge upload format)
+        run: pnpm pack:zip
+
+      - name: Pack xpi (Firefox Add-ons)
+        run: pnpm pack:xpi
+
+      - name: Pack crx (self-host sideload)
+        # crx 需要稳定 key.pem 才能保持插件 ID 不变；CI 没有就跳过，不阻塞主流程。
+        # 想生成稳定 crx：把 key 存到 secret EXTENSION_CRX_KEY，下面解开几行。
+        run: |
+          # if [ -n "${{ secrets.EXTENSION_CRX_KEY }}" ]; then
+          #   echo "${{ secrets.EXTENSION_CRX_KEY }}" > key.pem
+          #   pnpm pack:crx
+          # else
+            pnpm pack:crx || true
+          # fi
+        continue-on-error: true
+
+      - name: Rename artifacts with version suffix
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          [ -f extension.zip ] && mv extension.zip "bilinote-extension-${VERSION}.zip"
+          [ -f extension.xpi ] && mv extension.xpi "bilinote-extension-${VERSION}.xpi"
+          [ -f extension.crx ] && mv extension.crx "bilinote-extension-${VERSION}.crx"
+          ls -la *.zip *.xpi *.crx 2>/dev/null || true
+
+      - name: Attach to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            BillNote_extension/bilinote-extension-*.zip
+            BillNote_extension/bilinote-extension-*.xpi
+            BillNote_extension/bilinote-extension-*.crx
+          fail_on_unmatched_files: false
+          generate_release_notes: false
+
+# ---------- 商店自动发布（默认禁用，配齐 secrets 后可启用） ----------
+#
+#  publish-chrome:
+#    needs: build
+#    runs-on: ubuntu-latest
+#    steps:
+#      - uses: actions/download-artifact@v4
+#      - uses: mnao305/chrome-extension-upload@v5
+#        with:
+#          file-path: BillNote_extension/bilinote-extension-${{ github.ref_name }}.zip
+#          extension-id: ${{ secrets.CHROME_EXTENSION_ID }}
+#          client-id: ${{ secrets.CHROME_CLIENT_ID }}
+#          client-secret: ${{ secrets.CHROME_CLIENT_SECRET }}
+#          refresh-token: ${{ secrets.CHROME_REFRESH_TOKEN }}
+#
+#  publish-edge:
+#    needs: build
+#    runs-on: ubuntu-latest
+#    steps:
+#      - uses: wdzeng/edge-addon@v2
+#        with:
+#          product-id: ${{ secrets.EDGE_PRODUCT_ID }}
+#          zip-path: BillNote_extension/bilinote-extension-${{ github.ref_name }}.zip
+#          client-id: ${{ secrets.EDGE_CLIENT_ID }}
+#          api-key: ${{ secrets.EDGE_API_KEY }}
+#
+#  publish-firefox:
+#    needs: build
+#    runs-on: ubuntu-latest
+#    steps:
+#      - uses: trmcnvn/firefox-addon@v3
+#        with:
+#          uuid: ${{ secrets.FIREFOX_ADDON_UUID }}
+#          xpi: BillNote_extension/bilinote-extension-${{ github.ref_name }}.xpi
+#          api-key: ${{ secrets.FIREFOX_API_KEY }}
+#          api-secret: ${{ secrets.FIREFOX_API_SECRET }}