zheromiku/eng-standards-main
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
31 Commits 1 Branch 0 Tags
main
Commit Graph

9 Commits

Author SHA1 Message Date
姚章浩 79c154f9af docs: 版本条目改固定四类 + 破坏性变化固定写法 + 构建身份（口径变更） 
对着试点仓落地时暴露的问题做的口径与模板修正（本轮不推、不打 tag、不部署）：

- 条目形状：四个自定义必填节 → **固定四类** Added/Changed/Fixed/Security
  （分类可省略、不许空栏目）；过程记录进 docs/archive/，未合并事项进 docs/BACKLOG.md。
- 破坏性变化/迁移：固定写在 Changed 里、以 `**破坏性**` 开头并**必须链接发布文档**，
  仓内 `docs/….md` 链接**对账**（不存在即红）。
- 构建身份：release_version / build_kind / commit_sha / display_version / built_at；
  开发构建显示 X.Y.Z-dev+g<短SHA>（无基线 dev+g<短SHA>），**不许只显示上一正式版本号、
  不许自称正式版**；release 只认显式发布上下文。
- **还没有正式版本一律放行**：不判红；首个正式版本号**由人指定**（预检把它列成阻塞项）。
- **没核对远端就不许说校验成功**：CI/预检用 `--require-remote`（本地模式明确写「未核对远端」）。
- 修正"CI 取不到 tag 所以不用 tag"的过时口径：正式版本**就是**用注释 tag，
  只是**构建时不要用 git describe 取版本号**；**测试 tag 只在临时测试仓库里创建**。
- 模板同步：templates/check-changelog.py、templates/release-preflight.py、
  新增 templates/version.py；ci-gate.py 的 version 项在 CI 下强制核对远端；
  new-project.sh 落 scripts/version.py 并按四类重写 CHANGELOG 骨架；
  README/07/模板 README 同步；04 增加 §I（V-1~V-4 四条，含负例在哪）。

验证：templates 两个检查器 --self-test 全过；new-project.sh bash -n 通过；
生成的新工程里 check_changelog --tags 绿、--identity 给出 dev+g<短SHA>、
CI=true 下 version 项因"未核对远端"判红（预期）；试点仓反向夹具 80/0。
 2026-10-13 14:59:48 +08:00
姚章浩 718cfad3de docs: 正本 §6 重写 + 新增 07 发版操作说明（注释 tag 与 Release） 
§6 从原来的『构建注入 + 默认不打 tag』两条，重写为：版本权威来源按项目声明（knowledge-governance = CHANGELOG 顶部）、版本号格式与 Unreleased、正式版本四节、注释 tag v<版本号> + Gitea Release（人批准，CI 不代劳）、CI 成功/正式发版/部署三态分开、CI 必查项（无 tag 不判红）、只读发布预检入口。文档顶部标出与旧版的五处差异。07 写清步骤、命令、读回判据与常见错误。
 2026-10-12 17:58:06 +08:00
姚章浩 bda26730f5 fix(template): 同批次同步 bootstrap 启动、新分支基准与 Python 锁定隔离 
模板 workflow 第一步改成最小 bootstrap（空工作区里仓内脚本还不存在）；ci_checkout.sh 拆成 --post-checkout（检出后校验与补取：默认分支引用、事件 before）+ --print-remote；ci_gate.py 新分支范围以远端默认分支为基准；ci-gate.py 的 Python 依赖必须按 uv.lock 安装（uv sync --frozen）、所有检查走 uv run --frozen（项目内 .venv），并断言 sys.prefix != sys.base_prefix，缺锁/只有 requirements.txt 明确失败（不再 uv pip install --system）。文档补第三轮修正记录、trap 与自检命令。
 2026-10-12 16:45:10 +08:00
姚章浩 062bea41d0 docs: 第二轮修正记录、自检命令表与 README 入口 2026-10-12 11:15:32 +08:00
姚章浩 5b65ed9579 docs: 正本与 Runbook/接入文档口径同步（测试语义、CI-CD 分离、门禁唯一入口、必需检查清单） 
按草案逐条落到正本，并把三处已知错误的口径改回：

① 测试语义：删掉"单测跑的是构建产物，不是源码"这条被过度推广的说法。
   只有"跑产物"的套件（端到端 / 契约 / 产物自检）才必须排在构建之后；
   go test 自己编译测试程序、pytest 直读源码、vitest 默认也跑源码。
   写错这条的代价是给每个套件加假依赖、拖慢门禁并制造假故障。T8 同步改。
② CI 与 CD 分离：触发表删掉"推默认分支 → 自动部署测试环境"，作业划分表删掉 deploy:test 行，
   §4.6 标注为"项目自己的 CD、不属于通用 CI"，速查表同步。
③ 门禁入口：统一为 make verify（名字可不同，但 AGENTS/Runbook/CI 必须指同一个），
   §3.1、§8 清单、§9 速查表一致。
④ 新增 §4.8「必需检查清单与结果口径」：10 项必需检查的判据表 + 三条结果口径
   （失败即停但汇总照做、not_run/skipped 不算过、汇总故障不能报绿），
   以及预览/通知作为旁路的规则。
⑤ 接入文档：修掉"直推也拦得住"这句错口径，并写明接入器不再自动合并、
   --merge-pr 会先核对状态；试点记录里那一步标注为"当时的自动合并行为已改"。
⑥ 03/04/05 里的同源表述一并同步（生成物 jobs 与假成功占位的判据）。

验证：本批 18 处精确替换在脚本里逐处断言"恰好命中 1 次"（DRY-RUN 先过一遍再应用）；
替换后全仓 grep 复查，旧口径只在"说明它已被改掉"的上下文里出现。
 2026-10-12 00:12:06 +08:00
姚章浩 85f2471626 feat(adopt): 既有工程接入器 + 接入文档（含 PR 锁死陷阱的判定） 
问题：只有"新工程生成器"，没有"既有工程怎么接进来"的可复用路径；
而手工接入时最容易踩的坑是——盲目开"必须状态检查通过"，会让 PR
永远等一个不会出现的检查，永远合不了。

新增：
- scripts/adopt-existing.py：体检 → 加指针（分支+PR）→ 开保护 → 打印自检命令。
  默认 DRY-RUN 不动任何东西；幂等（重复跑不改 main）。
  关键设计：状态检查是否开启由体检判定——只有"推任意分支都会跑"的工作流，
  PR 头提交才带着 (push) 状态；判定不通过就只开"禁直推+必须 PR"。
- 06-接入既有工程.md：判定表（带 7 个仓的实测结论）、一条命令、试点记录、
  手工四步、验收判据、会遇到的拒绝与处理、扩到其余仓的顺序。

试点实测（Weknora/knowledge-governance）：PR #1 → CI context
build / build (push) success → mergeable=True（证明状态检查认 PR）→
合并 32b0ec58a612 → AGENTS.md 进 main；直推被 pre-receive 拒绝；
再跑 --apply 幂等，main 不变。

顺带修两个自查出来的毛病：
- ~/.git-credentials 里 LAN 主机是 URL 编码的（192.168.50.223%3a3000），
  按字面匹配会报"没有凭据"——改成解码后比对。
- runner 只在仓库级查，aiball 的 runner 挂在组织上，会误报"无 runner"。
 2026-10-10 16:26:02 +08:00
姚章浩 cb5985ff9e feat(apply): 应用机制 + 新工程生成器，让规范默认生效 
问题：规范此前只是文档，只有"有人去读"一个渠道 —— 实测 7 个仓 0 个有
AGENTS.md 指针、分支保护全空，起新工程时不会自动带上规范。

落地三件：
- scripts/new-project.sh：一条命令生成 9 个默认合规文件（提交闸门、CI、
  本地门禁、指针、提交规范 docs）。已端到端测过：空目录成功、非空拒绝、
  生成物 YAML 合法、无构建入口时门禁 exit 1（不静默通过）、默认分支 main。
- templates/ 收进 ci_gate.py / ci_report.py 的逐字节副本（cmp 校验通过），
  正本仓自此自包含，生成器不再依赖别的仓。
- 05-应用机制.md：写清 Hermes 的实际注入机制与两个必须避开的坑
  （每会话只加载一个上下文文件且有 20k 上限；不要把规则放 ~/.hermes/AGENTS.md
  —— 它只在 cwd 恰好是 ~/.hermes 时加载）。
- README / 03 加索引与交叉引用。

顺带修一个自己踩的坑：生成出来的 scripts/verify.sh 日志夹具只建不删，
正是正本 §3.2-5 自己写的陷阱（$TMPDIR 会攒到几万条）。改成成功时删除、
失败时保留并打印路径。
 2026-10-10 14:44:50 +08:00
姚章浩 419396f3ce docs(repo): 正本仓库名统一为 zheromiku/eng-standards-main 
本人建的仓名带了 -main 后缀（原计划写的是 eng-standards）。文档里 4 处
指向正本的引用（README、01-规范 §8、templates/README.md 的 AGENTS 骨架、
templates/gitea-build.yml 文件头）全部改成实际仓名与完整 URL，
避免留下一个指不到地方的指针。

本地工作副本仍为 ~/eng-standards/（仓名与本地目录名不一致是有意的：
改目录名会再次牵动已写好的引用，收益为零）。
 2026-10-10 14:30:25 +08:00
姚章浩 082afcf673 chore(repo): 规范仓库化 —— 从项目目录移到独立仓 
原先把规范放在 /srv/aiball/ci/standards/ 是分类错误：规范是跨仓的
（Weknora 三个仓 + aiball），却挂在单个项目（AI球）的目录下，
Weknora 侧的 AGENTS.md 要引用一个 aiball 路径，读起来就是错的。

改法：正本移到独立仓 ~/eng-standards（Gitea 远端 zheromiku/eng-standards
待本人网页创建），文档内 4 处旧路径引用一并更新，并补 .gitignore。

验证：git status 干净；grep 文档已无旧路径；提交信息闸门（~/.githooks/commit-msg）放行。
 2026-10-10 14:28:21 +08:00