95 lines
2.8 KiB
Markdown
95 lines
2.8 KiB
Markdown
---
|
|
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 编号 = 不合规
|