john
83 lines
4.6 KiB
Markdown
83 lines
4.6 KiB
Markdown
# 标准化开发测试发布约束
|
||
|
||
## 1. 仓库定位
|
||
|
||
1. 本仓库是 **本机 Mac 开发仓库**，不是生产目录。
|
||
2. `103` 是正式运行目标，`105` 是入口/代理层，**不是**源码真相所在处；不允许把它当作可直接同步或可直接 SSH 改码的开发延伸。细则见 [105 服务器变更规范](docs/105-server-operations.md)。
|
||
|
||
## 2. 开发约束
|
||
|
||
1. 新建开发分支前必须同步远端主线。推荐统一使用：
|
||
|
||
```bash
|
||
bash scripts/new-branch.sh feature/xxx
|
||
```
|
||
|
||
等价手工命令：
|
||
|
||
```bash
|
||
git fetch origin --prune
|
||
git switch main
|
||
git pull --ff-only
|
||
git switch -c feature/xxx
|
||
```
|
||
|
||
也可以直接从远端主线建分支：
|
||
|
||
```bash
|
||
git fetch origin --prune
|
||
git switch -c feature/xxx origin/main
|
||
```
|
||
|
||
2. 每次开发都必须形成本地 Git commit。
|
||
3. 一个 commit 只解决一类问题，避免把功能、环境、运维脚本混成一团。
|
||
4. 不允许长期堆积“只有自己知道用途”的未提交改动。
|
||
5. `.env`、账号、密钥、运行态数据不进入 Git。
|
||
6. 在“修复 bug / 开发中”这一阶段，默认只允许本地修改、本地运行、本地测试；**没有用户明确批准，不允许执行 `git push`、不允许生成或发布任何 `103` 相关 runtime/artifact、不允许合并或并入 `main`、不允许触发任何生产动作。**
|
||
7. 上一条中的“明确批准”必须是针对下一步动作本身的直接确认，不能把“继续看看”“先处理一下”之类表述解释成 `push`、发版、合并 `main` 的授权。
|
||
8. 即使代码已经改完，也必须先完成与本次改动对应的测试或 verify，并把结果核对清楚，再决定是否进入 `push`、合并 `main`、`103` 构建或发布等下一步。
|
||
9. 分支开发中如果主线继续变化，发布前必须重新对齐：
|
||
|
||
```bash
|
||
git fetch origin --prune
|
||
git rebase origin/main
|
||
```
|
||
|
||
## 3. 测试约束
|
||
|
||
1. 任何会发布的改动，至少要有最小可复现验证。
|
||
2. 只看首页 200 不算通过，必须验证本次功能真实路径。
|
||
3. 涉及数据结构变化时，必须写清楚兼容方式、回滚方式、补数据方式。
|
||
4. 如果用户已明确要求“先测试、测试后再决定下一步”，则在测试完成并得到新的明确批准前，禁止擅自执行 `git push`、合并 `main`、生成 `103` runtime/artifact、发布或重启线上服务。
|
||
|
||
## 4. 发布约束
|
||
|
||
1. 本机不允许直接 `rsync` 到 `103` 或 `105`。
|
||
2. **禁止** SSH 登录 `105` 后直接修改业务源码（含 `scripts/wechat-mp-menu.mjs` 等）；必须先本地 commit，再按发布流程上线。详见 [105 服务器变更规范](docs/105-server-operations.md)。
|
||
3. Portal 生产与测试统一走“本机构建 runtime artifact -> 打包发布”，**禁止**在 `103` 解源码包后 `npm install` / `npm run build`。
|
||
4. Portal 首次生产入口是 `bash scripts/release-portal-canary-prod.sh`；它只安装并启用用户级灰度候选。`bash scripts/release-portal-runtime-prod.sh` 是整包晋升脚本，在同一候选完成灰度验收且晋升证据校验落地前继续禁止非 dry-run。
|
||
5. 发布只能从已验证的完整 `main` 打整包；分支代码必须先合并进 `main`，禁止从功能分支、单个 commit、单个修复或局部差异单包发布。
|
||
6. 发布前必须确认 CI 已通过，且没有未合并的关键变更。
|
||
7. 发布来源必须是可追溯 commit，不允许从不明工作区直接出包。
|
||
8. 发布前必须有备份，发布后必须有健康检查和业务验收。
|
||
9. 发布前必须通过统一闸门：
|
||
|
||
```bash
|
||
bash scripts/check-release-ready.sh
|
||
```
|
||
|
||
10. 分支落后 `origin/main`、工作区有未提交或未跟踪改动、处于 detached HEAD、或没有明确批准却从 `main` / `master` 发布，均禁止发版。
|
||
11. 生产 `103` 发布必须完整通过 [生产发布守门员](docs/production-release-guardian.md)；Gate report 必须绑定同一完整 `main` commit 和同一 runtime artifact，且所有适用场景成功后仍须取得明确人工批准。
|
||
|
||
## 5. 文档约束
|
||
|
||
1. 端口、主机、运行目录、发布入口发生变化时，文档必须同次更新。
|
||
2. 如果一个事故已经查明根因，要把根因和排查入口写进仓库文档，而不是只留在聊天记录里。
|
||
|
||
## 6. 建议长期执行的附加规范
|
||
|
||
1. 发布前要求工作区可读：`git status` 不能混入无关改动。
|
||
2. 为每次正式发布保留 manifest、备份包路径、验证结果。
|
||
3. 涉及数据库、计费、用户空间、鉴权的改动，要额外保留一份业务验收清单。
|
||
4. 每个 AI 工具都必须先读本文件；自动化工具、Git hook、发布脚本以 `scripts/check-release-ready.sh` 的结果为准。
|