feat(docs,scripts,build): 用 docfx 搭文档站并发布到 GitHub Pages，版本号收口成脚本迭代
文档站（`docs/` 就是 docfx 项目，发布在 https://lovechengke.github.io/ClassHelper/）： - 四章 + 常见问题 + 完整参考，共 44 页：快速上手（8 页）/ 应用帮助（10 页）/ 管理运维（6 页）/ 开发文档（11 页）。信息架构照 ClassIsland 文档站来： 顶栏分章、左侧章节导航、右侧本页目录、上一页 / 下一页、站内搜索、深色主题跟随系统； - 自定义模板覆盖（`templates/classhelper/`）：把 docfx modern 模板那套英文 UI 文案 （In this article / Improve this doc / Next…）换成中文，补 GitHub 入口与版本徽标， 并加一层只调排版与配色的 `public/main.css`（不动 DOM 结构）； - 站点顶栏的版本徽标取自根 `package.json`（`docs/build.mjs` 用 `--metadata` 注入）， 不在文档里写第二份 —— 否则一定漂； - 404 页单独生成：GitHub Pages 的项目页挂在 `/<仓库名>/` 子路径下，而浏览器是按**被请求的路径** 解析页面里的相对链接的，所以 `<base>` 必须钉到站点根，由 `build.mjs`（本地 `./`）与 workflow（CI 传 `/<仓库名>/`）分别注入； - 构建前清空 `_site`：docfx 只覆盖不清理，删掉或改名的页面会以旧文件留在目录里， 而 Pages 上传的是整个目录。 版本迭代（**每一次 releases，不是每一次提交**）： - 新增 `scripts/version.mjs`。这个仓库里同一个版本号散在 **10 个文件**里（5 份 `package.json`、 `deploy/package.runtime.json`、两个 compose 的镜像 tag、插件 `manifest.yml`、以及插件 C# 里的 `PluginVersion` 常量），手工改必然漏一处，而漏掉的那处**不会报错**，只在某个不常走的分支上 表现为"版本号对不上"。现在收口成两条命令：`pnpm version:check`（逐处比对，不一致 exit 1） 与 `pnpm version:bump patch|minor|major`（一次改写全部 10 处，任何一处匹配不到或匹配到多处 就直接失败退出，不做尽力而为的部分改写）； - `AGENTS.md` 新增 §4.4「版本迭代（每一次 releases，不是每一次提交）」：写清版本号落在哪 10 处、 完整发布命令序列（体检 → 验收 → `dist:all` → 哈希清单 → 推 master → `gh release create` → Linux 包由 CI 合并哈希行），以及"已发布的版本号不要复用"的理由。 其它： - `.github/workflows/docs.yml`：推 master（`docs/**` / `package.json` / workflow 自身有变）即构建并 部署到 Pages；构建带 `--check`，把 docfx 的警告当错误 —— 最常见的警告是"某个 `.md` 没被任何 `toc.yml` 引用"，那种页面有内容但没有侧边栏，属于必须修掉的疏漏； - docs 目录重组后的引用同步：`production` / `mysql` / `linux-deploy` / `winisland-design-tokens` 移到新位置后，AGENTS.md、`deploy/`、`scripts/`、客户端源码注释里的路径引用一并更新； - 文档站只发布 `docs/` 这一棵树，页面里指向树外的相对链接（`../AGENTS.md` 等）改成 GitHub 绝对 URL， 否则上线全是 404； - 图标派生清单补上文档站模板里的 `logo.png` 与 `favicon.png`（`pnpm icons` 一并生成， 仍然只有一个图形源 `build/classhelper.{png,ico}`）； - `docs/_site` 进 `.gitignore` / `.prettierignore` 与 ESLint ignores； - 根脚本补 `version:check` / `version:bump` / `docs:build` / `docs:serve` / `docs:check`。
This commit is contained in:
LoveChengke committed
1 parent
5b002a4f0b
commit
19c2aa07b2
61 files changed
+4761
-12
No files matched your search
@@ -0,0 +1,184 @@
|
||||
---
|
||||
title: 版本迭代与发布
|
||||
description: 改版本号、跑验收、打安装包、发 GitHub Release、发布文档站——一次完整发布的命令清单。
|
||||
---
|
||||
|
||||
# 版本迭代与发布
|
||||
|
||||
## 一条总原则
|
||||
|
||||
> **版本号按「发布」迭代，不按「提交」迭代。**
|
||||
|
||||
日常的 `feat` / `fix` 提交**不动版本号**。只有当你要产出一批安装包、在 GitHub 上开一个 Release 时，
|
||||
才走一次完整的版本迭代。理由很实际：安装包、`.cipx`、Docker 镜像 tag、文档站的版本徽标、
|
||||
更新检查接口全都按版本号对齐；每次提交都动它，等于每天都在发版，用户那边的「检查更新」就废了。
|
||||
|
||||
| 算一次发布 | 不算 |
|
||||
| --------------------------------------- | ---------------------------- |
|
||||
| 攒够一批功能 / 修好一个用户能感知的 bug | 改注释、改文档、重构、加测试 |
|
||||
| 要给别人一份新安装包 | 只在自己机器上跑 |
|
||||
| 插件单独发补丁（只动插件第 4 段版本号） | — |
|
||||
|
||||
## 版本号写在哪（10 处）
|
||||
|
||||
同一个版本号出现在 10 个文件里，**手工改必然漏一处**，而漏掉的那处不会报错：
|
||||
|
||||
| 文件 | 内容 |
|
||||
| ---------------------------------------------------------------- | ------------------------------- |
|
||||
| `package.json` | 单一来源（服务端运行时读它） |
|
||||
| `packages/{shared,server,web-admin,desktop-client}/package.json` | 各包的版本 |
|
||||
| `deploy/package.runtime.json` | 安装包 / 容器里的运行时依赖清单 |
|
||||
| `deploy/docker-compose.yml`、`docker-compose.sqlite.yml` | 镜像 tag 的默认值 |
|
||||
| `packages/classisland-plugin/manifest.yml` | 插件清单（四段：`x.y.z.0`） |
|
||||
| `packages/classisland-plugin/src/Services/BridgeService.cs` | 插件上报的 `PluginVersion` 常量 |
|
||||
|
||||
所以**改版本号的唯一入口是脚本**：
|
||||
|
||||
```bash
|
||||
pnpm version:check # 逐处列出并比对，不一致 exit 1
|
||||
pnpm version:bump patch # 1.1.2 → 1.1.3
|
||||
pnpm version:bump minor # 1.1.2 → 1.2.0
|
||||
pnpm version:bump major # 1.1.2 → 2.0.0
|
||||
pnpm version:check # 再确认一次
|
||||
```
|
||||
|
||||
脚本按表逐个改写，**任何一处没匹配到或匹配到多处就直接失败退出**，不做"尽力而为"的部分改写。
|
||||
|
||||
> 插件版本是 **四段** `x.y.z.0`：前三段跟产品版本走，第 4 段留给"只改插件、不动产品版本"的补丁发布。
|
||||
> `--bump` / `--set` 会把第 4 段归零；要单独发插件补丁就手工改那两处（清单 + `BridgeService.cs`）。
|
||||
|
||||
## 一次完整的发布
|
||||
|
||||
下面这一串命令就是全部流程，逐条照抄即可。
|
||||
|
||||
### 1. 改版本号
|
||||
|
||||
```bash
|
||||
pnpm version:check
|
||||
pnpm version:bump patch
|
||||
```
|
||||
|
||||
### 2. 本地体检
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm check:icons
|
||||
pnpm docs:check # 文档站构建（警告即失败）
|
||||
```
|
||||
|
||||
### 3. 跑验收
|
||||
|
||||
```bash
|
||||
pnpm dev:server # 另开一个终端跑着
|
||||
|
||||
pnpm verify:e2e
|
||||
pnpm verify:classisland
|
||||
pnpm verify:classisland-plugin
|
||||
|
||||
pnpm build:desktop && pnpm verify:desktop
|
||||
pnpm build && pnpm verify:web
|
||||
```
|
||||
|
||||
哪一项红了先看[验收与测试](testing.md)的「失败时先别改代码」——
|
||||
里面列了几个已知脆弱的用例，它们红不代表代码坏了。
|
||||
|
||||
### 4. 打安装包
|
||||
|
||||
```bash
|
||||
pnpm dist:all # = dist:server + dist:win + dist:classisland-plugin
|
||||
```
|
||||
|
||||
产物落在 `releases/<组件>/<版本>/`：`安装包/`、`免安装/`、`构建中间/`。
|
||||
打完之后**对打包副本再验一次**（开发产物通过 ≠ 用户机器上的副本通过）：
|
||||
|
||||
```bash
|
||||
pnpm verify:packaged --exe "releases/client/<版本>/免安装/班级小助手.exe"
|
||||
```
|
||||
|
||||
> Linux 包**只能在 Linux 上构建**（依赖是平台相关的），所以不在这条命令里 ——
|
||||
> 它由 GitHub Actions 出，见第 7 步。
|
||||
|
||||
### 5. 生成跨组件哈希清单
|
||||
|
||||
`releases/SHA256SUMS-<版本>.txt` 是**人读的**（表头 + 体积 + 说明），由发布流程维护，
|
||||
本地只写 Windows 与插件那几行：
|
||||
|
||||
```bash
|
||||
cd releases/client/<版本>/安装包 && sha256sum *.exe > ../../../SHA256SUMS-<版本>.txt # 按实际文件名整理
|
||||
```
|
||||
|
||||
（Linux 那一行由 CI 在第 7 步里**合并**进去，不要手工写。）
|
||||
|
||||
### 6. 提交并推上去
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "chore(release): 1.1.3"
|
||||
git push origin master
|
||||
```
|
||||
|
||||
提交信息用 Conventional Commits + 模块 scope，描述写中文，可多 scope，例如
|
||||
`fix(island): 胶囊"点不动"的根因——窗口必须始终可激活`。
|
||||
|
||||
### 7. 开 Release
|
||||
|
||||
```bash
|
||||
gh release create v1.1.3 --title "v1.1.3" --generate-notes
|
||||
|
||||
gh release upload v1.1.3 \
|
||||
releases/client/<版本>/安装包/*.exe \
|
||||
releases/classisland-plugin/<版本>/安装包/*.cipx \
|
||||
releases/server/<版本>/安装包/*.exe \
|
||||
releases/SHA256SUMS-<版本>.txt --clobber
|
||||
```
|
||||
|
||||
`gh release create` 会**创建 tag 并推送**，这一步会自动触发
|
||||
[`release-linux-server.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/release-linux-server.yml)
|
||||
构建 Linux 包（ubuntu runner）。它跑完之后会：
|
||||
|
||||
1. 把 `classhelper-server-linux-x64-<版本>.tar.gz` 与 `.sha256` 挂到 Release 上；
|
||||
2. **把 Linux 那一行合并进** `SHA256SUMS-<版本>.txt`（保留 Windows / 插件那几行）。
|
||||
|
||||
> **顺序很重要**：Linux workflow 是在最后一步才去合并 SHA256SUMS 的，
|
||||
> 所以第 5 步那份清单必须**先上传**。万一手速反了（workflow 先跑完、你后上传），
|
||||
> 重新跑一次 `gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true` 就能把那一行补回来。
|
||||
|
||||
想手动触发（比如只需要重出 Linux 包）：
|
||||
|
||||
```bash
|
||||
gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true
|
||||
```
|
||||
|
||||
### 8. 文档站
|
||||
|
||||
**不用做任何事。** 推送 master 时只要 `docs/**` 或 docs 的 workflow 变过，
|
||||
[`docs.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/docs.yml)
|
||||
会自动用 docfx 构建并部署到 GitHub Pages。
|
||||
|
||||
文档站顶栏的版本徽标取自根 `package.json`，所以第 1 步改完就跟着变了。
|
||||
|
||||
### 9. 检查
|
||||
|
||||
- [ ] Release 页面上四个组件都在，`SHA256SUMS-<版本>.txt` 里 Windows / 插件 / Linux 三种行齐全；
|
||||
- [ ] 文档站能打开，顶栏版本号是新版；
|
||||
- [ ] 装一台机器试一遍（或至少跑 `pnpm verify:packaged`）。
|
||||
|
||||
## 回滚
|
||||
|
||||
发布出去之后发现严重问题：
|
||||
|
||||
| 情形 | 做法 |
|
||||
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| 只是文档 / Release 说明写错 | 直接改 Release 说明或重发文档站（`gh workflow run docs.yml`） |
|
||||
| 二进制有问题 | 删掉 Release 与 tag（`gh release delete v1.1.3 --cleanup-tag`），修完重新发；**不要**拿同一个版本号发第二次内容不同的包 |
|
||||
| 用户已经装了 | 发一个**新版本号**（`pnpm version:bump patch`）修复，不要原地改 |
|
||||
|
||||
> 已经发出去的版本号**不要复用**：客户端把它记进「忽略此版本」，服务端与 Web 端各有 30 分钟缓存，
|
||||
> 同号换内容会让"检查更新"永久失灵。
|
||||
|
||||
## 相关
|
||||
|
||||
- 文档站本身怎么写的 → [架构总览的目录结构](architecture.md)
|
||||
- 验收脚本与脆弱用例 → [验收与测试](testing.md)
|
||||
- 各形态升级的**用户侧**步骤 → [更新与升级](../management/upgrade.md)
|
||||
Reference in new issue
Block a user