release: v1.4.0

.github/BRANCHING.md

@@ -1,39 +1,42 @@
 # Branching and release
 
-This repo uses a lightweight git-flow. `main` stays the default working branch; shipping happens on `release`.
+This repo uses standard **git-flow** (with `main` as the production branch instead of the historical `master`).
 
 ## Branches
 
 | Branch | Role |
 |--------|------|
-| `main` | Day-to-day development (git-flow *develop*) |
-| `release` | Shippable line (git-flow *main*). Only merge work that is meant to ship |
-| `feature/<name>` | New work, branched from `main` |
-| `hotfix/<name>` | Production fixes, branched from `release` |
+| `main` | Production line (git-flow *master*). Only merge work that is meant to ship |
+| `develop` | Day-to-day development (git-flow *develop*). GitHub default branch |
+| `feature/<name>` | New work, branched from `develop` |
+| `bugfix/<name>` | Non-urgent fixes, branched from `develop` |
+| `release/<x.y.z>` | Release preparation / version bump, branched from `develop` |
+| `hotfix/<x.y.z>` | Production fixes, branched from `main` |
 
-Do not commit directly to `release`. Open a pull request.
+Do not commit directly to `main`. Open a pull request.
 
 ```
-feature/* ──PR──► main ──PR (version bump)──► release ──tag Vx.y.z──► CI
-hotfix/*  ──PR──► release ──tag──► CI
-                    └──PR──► main
+feature/* ──PR──► develop ──PR──► release/x.y.z ──PR──► main ──tag Vx.y.z──► CI
+bugfix/*  ──PR──► develop            │
+hotfix/*  ──PR──► main ──tag──► CI   └─merge back──► develop
+                  └─merge back──► develop
 ```
 
 ## First-time setup
 
-The workflow file must exist on the tagged commit, so create `release` from the commit that already contains `.github/workflows/release.yml` (after this work is on `main`):
+The workflow file must exist on the tagged commit, so create `main` (production) from the commit that already contains `.github/workflows/release.yml` (after this work is on `develop`):
 
 ```bash
 git fetch origin
-git checkout main
+git checkout develop
 git pull
-git checkout -b release
-git push -u origin release
+git checkout -b main
+git push -u origin main
 ```
 
 Then in GitHub:
 
-1. Protect `release` (PR required, no force-push).
+1. Set `develop` as the default branch, protect `main` (PR required, no force-push).
 2. Settings → Actions → General → Workflow permissions → **Read and write**. Without this, attaching `.exe` / `.dmg` to the GitHub Release fails.
 
 Existing tags such as `V1.3.1` will not rebuild automatically. The next *new* version tag is what starts CI.
@@ -42,28 +45,32 @@ Existing tags such as `V1.3.1` will not rebuild automatically. The next *new* ve
 
 All three must be true or GitHub Actions will not build installers:
 
-1. The commit lives on `release` (merged there, not only on `main`).
+1. The commit lives on `main` (merged there, not only on `develop`).
 2. `version.json` changed compared with the previous version tag.
 3. A version tag `Vx.y.z` or `vx.y.z` is pushed, and it matches `version.json`.
 
 Suggested sequence:
 
 ```bash
-# 1. On a branch from main: bump version.json, src-tauri/Cargo.toml,
+# 1. Branch release/x.y.z from develop: bump version.json, src-tauri/Cargo.toml,
 #    src-tauri/tauri.conf.json, and frontend/package.json to the same x.y.z
-git checkout main
+git checkout develop
 git checkout -b release/1.4.0
 
-# 2. Open a PR into release and merge it
+# 2. Open a PR into main and merge it
 
-# 3. Tag the merge commit on release, then push the tag
-git checkout release
+# 3. Tag the merge commit on main, then push the tag
+git checkout main
 git pull
 git tag V1.4.0
 git push origin V1.4.0
+
+# 4. Merge main back into develop so development is not left behind
 ```
 
-Pushing the tag is what starts the workflow. The gate job then re-checks the other two conditions. If any check fails, Windows/macOS builds are skipped.
+Pushing the tag is what starts the workflow. The gate job (`scripts/ci-release-gate.sh`) then re-checks the three conditions. The production branch it verifies defaults to `main` and can be overridden with the `RELEASE_GATE_PROD_BRANCH` environment variable. If any check fails, Windows/macOS builds are skipped.
+
+Do not add version lines to `README.md` / `README.zh-CN.md`. Those files link to [Releases](https://github.com/Gyanano/RSerialDebugAssistant/releases); CI fills the GitHub Release body from commits since the previous tag.
 
 Artifacts:
 
@@ -74,4 +81,4 @@ macOS signing uses GitHub Actions secrets (`APPLE_CERTIFICATE`, `APPLE_CERTIFICA
 
 Intel Mac `.dmg` is not built yet.
 
-Hotfix: branch from `release`, bump the patch version, PR back into `release`, tag, then PR `release` into `main` so development is not left behind.
+Hotfix: branch `hotfix/x.y.z` from `main`, bump the patch version, PR back into `main`, tag, then merge `main` back into `develop` so development is not left behind.

.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+# PR-level safety net. Runs the Rust test suite and a frontend type-check + build.
+# Release packaging stays in release.yml (tag pushes only).
+on:
+  pull_request:
+    branches: [develop, main]
+  push:
+    branches: [develop]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  rust:
+    name: Rust test
+    # macOS matches the release runner and needs no extra system packages for Tauri.
+    runs-on: macos-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Rust cache
+        uses: swatinem/rust-cache@v2
+        with:
+          workspaces: src-tauri
+
+      # tauri::generate_context! requires frontendDist to exist at compile time.
+      - name: Create frontend dist placeholder
+        run: |
+          mkdir -p frontend/dist
+          echo '<!doctype html><title>ci placeholder</title>' > frontend/dist/index.html
+
+      - name: Run tests
+        working-directory: src-tauri
+        run: cargo test
+
+  frontend:
+    name: Frontend typecheck + build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        working-directory: frontend
+        run: npm install
+
+      - name: Type-check
+        working-directory: frontend
+        run: npx tsc --noEmit
+
+      - name: Build
+        working-directory: frontend
+        run: npm run build

.github/workflows/release.yml

@@ -1,7 +1,7 @@
 name: Release
 
 # Tag push is the only trigger. The gate job then requires:
-#   1. the tagged commit is on `release`
+#   1. the tagged commit is on `main` (the production branch)
 #   2. version.json changed vs the previous version tag
 #   3. the tag is Vx.y.z / vx.y.z and matches version.json
 on:
@@ -109,3 +109,21 @@ jobs:
           releaseDraft: false
           prerelease: false
           args: ${{ matrix.args }}
+
+  release-notes:
+    name: Fill release notes
+    needs: [gate, build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Generate notes from commits since the previous tag
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          NOTES="$(gh api "repos/${REPO}/releases/generate-notes" -f tag_name="${TAG}" --jq .body)"
+          BODY="$(printf '%s\n\n%s\n' "${TAG}" "${NOTES}")"
+          gh release edit "${TAG}" --repo "${REPO}" --notes "${BODY}"

.gitignore

@@ -61,4 +61,6 @@ coverage/
 !README.md
 !README.zh-CN.md
 !AGENTS.md
+!CONTRIBUTING.md
+!CONTRIBUTING.zh-CN.md
 !.github/**/*.md

AGENTS.md

@@ -2,7 +2,7 @@
 
 Tauri 2 + React 18 串口调试工具。前端在 `frontend/`，Rust 在 `src-tauri/`。UI 用 shadcn（new-york / zinc），组件在 `frontend/src/components/ui/`。
 
-发版流程、分支模型和 CI 门禁的完整说明在 `.github/BRANCHING.md`。改 CI、打 Tag、合 `release` 之前先读它。
+发版流程、分支模型和 CI 门禁的完整说明在 `.github/BRANCHING.md`。改 CI、打 Tag、合 `main`（生产线）之前先读它。
 
 ## 本地运行（macOS）
 
@@ -47,12 +47,68 @@ macOS CI 用 Developer ID Application 签名 + App Store Connect API 公证。
 
 双端安装包（Windows NSIS `.exe` + macOS Apple Silicon `.dmg`）只在推送版本 Tag 时启动，并由 `scripts/ci-release-gate.sh` 再检查：
 
-1. 该 Tag 的 commit 在 `origin/release` 上（合进了 release，不是只在 `main`）
+1. 该 Tag 的 commit 在 `origin/main`（生产线）上（合进了 main，不是只在 `develop`）
 2. `version.json` 相对上一个版本 Tag 有变更
 3. Tag 为 `Vx.y.z` / `vx.y.z`，且与 `version.json` 一致
 
 缺一则不编译。工作流：`.github/workflows/release.yml`。
 
-分支：`main` = 日常开发；`release` = 发版线，不要直接往 `release` 上提交。`feature/*` 从 `main` 拉，`hotfix/*` 从 `release` 拉。
+不要在 README 里手写版本号或版本历史。最新版本用 GitHub Release 徽章显示，变更说明由 CI 根据两次 Tag 之间的提交生成，写在 GitHub Releases 上。
 
-第一次启用 CI：先把含 workflow 的 commit 推到 `main`，再从该 commit 建并推送 `release`；GitHub Actions 权限设为 Read and write。已有 Tag（如 `V1.3.1`）不会自动重编。
+分支（标准 git-flow）：`main` = 生产发版线，不要直接往 `main` 上提交；`develop` = 日常开发（GitHub 默认分支）。`feature/*`、`bugfix/*`、`release/x.y.z` 从 `develop` 拉，`hotfix/x.y.z` 从 `main` 拉。
+
+## git-flow 常用流程
+
+注意：把分支**推送**到远端不会删除本地分支；删除发生在"完成"时（PR 合并后，或 `git flow feature finish`）。远端分支要单独删（GitHub 合并 PR 后点 Delete branch，或 `git push origin --delete <branch>`）。
+
+### feature / bugfix（日常开发，从 develop 拉）
+
+```bash
+git checkout develop && git pull
+git checkout -b feature/xxx            # bugfix 同理：bugfix/xxx
+# …开发、提交（Conventional Commits）…
+git push -u origin feature/xxx         # 推送不删本地分支
+# 开 PR 合入 develop，合并后清理：
+git checkout develop && git pull
+git branch -d feature/xxx
+git push origin --delete feature/xxx   # 或在 GitHub 上点 Delete branch
+```
+
+本地只有小改动、不走 PR 时，可以直接 `--no-ff` 合回 develop 再删分支（仓库里 `1da5a4f` 就是例子）。
+
+### release/x.y.z（发版，从 develop 拉）
+
+```bash
+git checkout develop && git pull
+git checkout -b release/1.4.0
+# 提升 version.json / Cargo.toml / tauri.conf.json / frontend/package.json 到同一版本
+git push -u origin release/1.4.0       # 开 PR 合入 main
+git checkout main && git pull
+git tag V1.4.0 && git push origin V1.4.0   # 推 Tag 触发 CI 构建
+git checkout develop && git merge --no-ff main   # 回合 develop
+git push origin develop
+git branch -d release/1.4.0 && git push origin --delete release/1.4.0
+```
+
+### hotfix/x.y.z（紧急修复，从 main 拉）
+
+```bash
+git checkout main && git pull
+git checkout -b hotfix/1.3.2
+# 修复 + 提升四个文件的 patch 版本
+git push -u origin hotfix/1.3.2        # 开 PR 合入 main
+git checkout main && git pull
+git tag V1.3.2 && git push origin V1.3.2
+git checkout develop && git merge --no-ff main   # 修复回合 develop
+git push origin develop
+git branch -d hotfix/1.3.2 && git push origin --delete hotfix/1.3.2
+```
+
+### 同步与清理
+
+```bash
+git fetch --prune                      # 清理远端已删除分支的本地跟踪
+git checkout develop && git pull       # 日常开工前保持 develop 最新
+```
+
+第一次启用 CI：先把含 workflow 的 commit 推到 `develop`，再从该 commit 建并推送 `main`（生产线）；GitHub Actions 权限设为 Read and write。已有 Tag（如 `V1.3.1`）不会自动重编。