# 维护者发布流程

本文用于维护项目。使用者请阅读[README](<../README.md>)和[安装指南](https://github.com/f-e-n-g-0531/dsh-vcs/blob/main/docs/INSTALL.md)。

## 发布内容

每次改动完成并验证通过后，主动完成 npm 与 GitHub 正式发布，不停留在本地修改或只推标签。版本使用 `vX.Y.Z`：X 为大版本，Y 为小版本／新增功能，Z 为 BUG 修复；递增前一位时后面的位归零。失败门禁必须先修复，不能为了发布跳过验证。发布不自动安装或重启宿主。

每个新版本必须有独立的中文发布说明，放在 `docs/releases/版本号.md`。按“本版变化、安装、限制、验证”组织，不把自动提交列表、开发轮次或内部恢复记录当作用户说明。没有新增功能时明确写出，不夸大改动。

更新包版本和锁文件，在变更记录中填写同一版本。核查许可证、第三方声明及公开文件，排除凭据和私人数据。

## 1. 本地检查

需要 Node.js 22+、Git、SVN、svnadmin。在干净检出中执行：

	npm ci --include=dev
	npm run check
	npm run verify:package
	npm run test:install

测试失败或跳过须调查；隔离安装只检查包和宿主注册，不是用户实际 DSH 验收。

## 2. 固定版本并验证

1. 提交并推送版本修改，创建新标签 `vX.Y.Z`；不移动已有标签。
2. 等待标签 CI 的 Windows／Ubuntu × Node 22／24 全部成功。
3. 手动在同一标签运行 **Browser layout checks**，等待成功。
4. 下载四个 CI 候选 tgz，确认字节大小和 SHA-256 全部一致。

分支检查不能代替同标签检查。失败后先定位；需要修改源码或测试时使用新的版本和标签。

## 3. 联合发布

在 Actions 从 main 运行 **Publish GitHub and npm**，输入已验证的标签。

工作流检出该标签，重新检查并打包。它先上传 npm，再验证公开 npm 元数据与实际下载包，最后创建 GitHub 正式 Release，上传同一个 tgz 和 SHA-256 校验文件。

仓库需配置 `NPM_AUTOMATION_TOKEN`，具有该包发布权限并符合 npm 2FA 策略。凭据只用于上传步骤；不要写进源码、发布说明或聊天。

## 4. 发布后核验

- npm 版本与 latest 正确，实际 tarball 可下载。
- GitHub Release 非草稿、非预发布，附件可下载。
- 两端实际包与四候选的字节大小和 SHA-256 一致。
- 补记最终结论，但不修改已发布标签或替换工件。

npm 与 GitHub 不是原子发布。若 npm 已接受上传但公开下载暂时 404，**不要再次上传**；先只读确认公开包。确认相同后恢复原失败任务，工作流会核对已有 npm integrity 并跳过上传。不匹配则停止；已有 GitHub Release 不覆盖。

## 实机验证与安装边界

自动浏览器测试不等于当前 DSH 实机通过。发布说明须如实写出未确认项；用户明确授权在此边界下发布时，不伪造实机结论。

发布不安装、不升级、不重启运行中的 DSH。用户选择安装后，在原 Web 页面检查入口、仓库发现、差异、历史以及 Session 切换；由用户自行重启。维护者不能启动替代服务器冒充当前页面。