skills/hermes/gitea-dev-workflow/SKILL.md

name, version, description, metadata

name	version	description	metadata
gitea-dev-workflow	1.0.0	沙洲家族 Gitea 项目通用开发规范。所有在 git.shazhou.work 上的项目必须遵守。 涵盖提交纪律、测试纪律、分支管理等基本规则。	hermes tags related_skills gitea workflow discipline testing commit requesting-code-review rfc-iteration test-driven-development

Gitea 项目开发规范

所有 git.shazhou.work 上的项目必须遵守以下规范。

铁律（不可违反）

1. 禁止 --no-verify

永远不要使用 git push --no-verify 或 git commit --no-verify。

• 如果 pre-commit / pre-push hook 失败，必须修复问题而不是绕过检查
• 如果 hook 本身有 bug 导致误报，应该修复 hook，而不是跳过它
• 没有例外，没有"先推上去再说"

2. 测试必须通过才能推送

• 推送前确保所有测试通过
• CI 状态检查必须绿色才能合并 PR

Flaky Test 处理流程

当遇到不稳定测试（时过时不过）：

Step 1：确认是 flaky test

• 同一测试在无代码变更的情况下，多次运行结果不一致
• 记录失败频率和错误信息

Step 2：请求主人批准

• 向主人报告 flaky test 的情况（测试名、失败频率、错误信息）
• 必须获得主人明确同意才能禁用测试
• 未经批准不得自行跳过或禁用任何测试

Step 3：禁用测试 + 开 Issue

批准后：

1. 用框架对应的方式标记跳过（不要删除测试代码）：

   # Python pytest
   @pytest.mark.skip(reason="Flaky: #<issue-number> - <简要描述>")
   

   // Vitest / Jest
   it.skip('test name') // Flaky: #<issue-number> - <简要描述>
   

   // Go
   t.Skip("Flaky: #<issue-number> - <简要描述>")
   

2. 在 Gitea 上开 Issue 跟踪：

   • 标题：Flaky test: <测试名>
   • 内容：失败频率、错误日志、可能的根因分析
   • Label：flaky-test（如果有的话）

3. Skip 注释里必须引用 Issue 编号

Step 4：长期跟进

• Flaky test issue 不应长期搁置
• 修复后恢复测试并关闭 Issue

分支管理

• main 分支受保护的项目（如 nerve）：必须开 PR，不能直接推
• 其他项目：可以直接推 main，但建议复杂改动走 PR
• 分支命名：feat/xxx、fix/xxx、chore/xxx

提交信息

遵循 Conventional Commits：

• feat: 新功能描述
• fix: 修复描述
• chore: 杂项
• refactor: 重构描述
• docs: 文档更新
• test: 测试相关

Pitfalls

• hook 太慢不是跳过的理由 — 优化 hook，不要 --no-verify
• "本地能过 CI 过不了" — 以 CI 为准，修到 CI 也过
• 禁用测试忘记开 Issue — skip 注释里没有 issue 编号 = 不合规