From e7811d073d9f944a5d5ff96e4603a8d224540b13 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=9B=A2=E5=AD=90?= <tuanzi@shazhou.work>
Date: Tue, 28 Apr 2026 04:35:57 +0000
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20gitea-dev-workflow?=
 =?UTF-8?q?=20skill=20=E2=80=94=20=E9=80=9A=E7=94=A8=E5=BC=80=E5=8F=91?=
 =?UTF-8?q?=E7=BA=AA=E5=BE=8B=E8=A7=84=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 hermes/gitea-dev-workflow/SKILL.md | 94 ++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 hermes/gitea-dev-workflow/SKILL.md

diff --git a/hermes/gitea-dev-workflow/SKILL.md b/hermes/gitea-dev-workflow/SKILL.md
new file mode 100644
index 0000000..7db3162
--- /dev/null
+++ b/hermes/gitea-dev-workflow/SKILL.md
@@ -0,0 +1,94 @@
+---
+name: gitea-dev-workflow
+version: 1.0.0
+description: >
+  沙洲家族 Gitea 项目通用开发规范。所有在 git.shazhou.work 上的项目必须遵守。
+  涵盖提交纪律、测试纪律、分支管理等基本规则。
+metadata:
+  hermes:
+    tags: [gitea, workflow, discipline, testing, commit]
+    related_skills: [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
+   # Python pytest
+   @pytest.mark.skip(reason="Flaky: #<issue-number> - <简要描述>")
+   ```
+   ```javascript
+   // Vitest / Jest
+   it.skip('test name') // Flaky: #<issue-number> - <简要描述>
+   ```
+   ```go
+   // 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 编号 = 不合规