---
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 编号 = 不合规