Skip to content

Commit 015f2fd

Browse files
jamiesunjamiesun
authored
feat: add GitHub workflows, branch protection, and automated code quality tools (#4)
- Add CI/CD workflows (test, lint, build, publish, auto-format) - Add pre-commit hooks for automatic code formatting - Add comprehensive documentation for code quality tools - Fix CI job names to match branch protection requirements - Format all code with black and isort - Add branch protection configuration guide This PR sets up the complete automated code quality and CI/CD infrastructure.
1 parent 04ef708 commit 015f2fd

33 files changed

+3375
-1999
lines changed

‎.github/BRANCH_PROTECTION.md‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
# 分支保护配置指南
2+
3+
## 为什么需要分支保护?
4+
5+
分支保护可以:
6+
7+
- ✅ 防止直接推送到主分支
8+
- ✅ 确保所有更改都经过 PR 审查
9+
- ✅ 强制 CI 测试必须通过
10+
- ✅ 要求代码审查
11+
- ✅ 保持代码质量和稳定性
12+
13+
## 推荐的分支保护规则
14+
15+
### 🔒 Main 分支保护 (强烈推荐)
16+
17+
#### 基础保护
18+
19+
1. **Require a pull request before merging** (合并前需要 PR)
20+
21+
- ✅ 启用此选项
22+
- Require approvals: 1 (至少 1 人审查)
23+
- ✅ Dismiss stale pull request approvals when new commits are pushed (新提交时清除旧审查)
24+
- ✅ Require review from Code Owners (如果有 CODEOWNERS 文件)
25+
26+
2. **Require status checks to pass before merging** (合并前需要状态检查通过)
27+
28+
- ✅ 启用此选项
29+
- ✅ Require branches to be up to date before merging (合并前需要更新分支)
30+
- 必需的状态检查:
31+
- `test (3.10)` - Python 3.10 测试
32+
- `test (3.11)` - Python 3.11 测试
33+
- `test (3.12)` - Python 3.12 测试
34+
- `test (3.13)` - Python 3.13 测试
35+
- `lint` - 代码质量检查
36+
- `build` - 包构建
37+
38+
3. **Require conversation resolution before merging** (合并前需要解决所有对话)
39+
40+
- ✅ 启用此选项
41+
42+
4. **Require signed commits** (需要签名提交)
43+
44+
- ⚠️ 可选 - 如果团队使用 GPG 签名
45+
46+
5. **Require linear history** (需要线性历史)
47+
48+
- ⚠️ 可选 - 防止合并提交,保持历史清晰
49+
50+
6. **Do not allow bypassing the above settings** (不允许绕过以上设置)
51+
- ✅ 启用此选项 (管理员也需遵守规则)
52+
53+
#### 其他规则
54+
55+
- ✅ **Restrict who can push to matching branches** - 限制谁可以推送
56+
- 只允许维护者推送
57+
- ✅ **Allow force pushes** - 关闭 (防止强制推送)
58+
- ✅ **Allow deletions** - 关闭 (防止删除主分支)
59+
60+
## 📋 配置步骤
61+
62+
### 方式 1: 通过 GitHub 网页配置 (推荐)
63+
64+
1. 访问仓库设置
65+
66+
```
67+
https://github.com/talkincode/hyperliquid-mcp-python/settings/branches
68+
```
69+
70+
2. 点击 "Add branch protection rule"
71+
72+
3. 在 "Branch name pattern" 中输入: `main`
73+
74+
4. 启用以下选项:
75+
76+
- ✅ Require a pull request before merging
77+
78+
- Required number of approvals: 1
79+
- ✅ Dismiss stale pull request approvals when new commits are pushed
80+
81+
- ✅ Require status checks to pass before merging
82+
83+
- ✅ Require branches to be up to date before merging
84+
- 添加必需的检查:
85+
- `test (3.10)`
86+
- `test (3.11)`
87+
- `test (3.12)`
88+
- `test (3.13)`
89+
- `lint`
90+
- `build`
91+
92+
- ✅ Require conversation resolution before merging
93+
94+
- ✅ Do not allow bypassing the above settings
95+
96+
5. 点击 "Create" 保存
97+
98+
### 方式 2: 通过 GitHub CLI 配置
99+
100+
```bash
101+
# 安装 GitHub CLI (如果未安装)
102+
brew install gh
103+
104+
# 登录
105+
gh auth login
106+
107+
# 创建分支保护规则
108+
gh api repos/talkincode/hyperliquid-mcp-python/branches/main/protection \
109+
--method PUT \
110+
--field required_status_checks='{"strict":true,"contexts":["test (3.10)","test (3.11)","test (3.12)","test (3.13)","lint","build"]}' \
111+
--field enforce_admins=true \
112+
--field required_pull_request_reviews='{"dismiss_stale_reviews":true,"require_code_owner_reviews":false,"required_approving_review_count":1}' \
113+
--field restrictions=null
114+
```
115+
116+
### 方式 3: 使用 Terraform (Infrastructure as Code)
117+
118+
创建 `terraform/github.tf`:
119+
120+
```hcl
121+
resource "github_branch_protection" "main" {
122+
repository_id = "hyperliquid-mcp-python"
123+
pattern = "main"
124+
125+
required_status_checks {
126+
strict = true
127+
contexts = [
128+
"test (3.10)",
129+
"test (3.11)",
130+
"test (3.12)",
131+
"test (3.13)",
132+
"lint",
133+
"build"
134+
]
135+
}
136+
137+
required_pull_request_reviews {
138+
dismiss_stale_reviews = true
139+
require_code_owner_reviews = false
140+
required_approving_review_count = 1
141+
}
142+
143+
enforce_admins = true
144+
require_conversation_resolution = true
145+
require_signed_commits = false
146+
allow_force_pushes = false
147+
allow_deletions = false
148+
}
149+
```
150+
151+
## 🎯 不同场景的推荐配置
152+
153+
### 个人项目 (轻量级)
154+
155+
```
156+
- ✅ Require status checks (CI must pass)
157+
- ⚠️ Require PR (可选,个人项目可以直接推送)
158+
- ⚠️ Require reviews (可选,个人项目不需要)
159+
```
160+
161+
### 小团队项目 (2-5 人)
162+
163+
```
164+
- ✅ Require status checks (CI must pass)
165+
- ✅ Require pull request before merging
166+
- ✅ Require 1 approval
167+
- ✅ Require conversation resolution
168+
```
169+
170+
### 开源项目 (推荐配置)
171+
172+
```
173+
- ✅ Require status checks (CI must pass)
174+
- ✅ Require pull request before merging
175+
- ✅ Require 1-2 approvals
176+
- ✅ Require conversation resolution
177+
- ✅ Require Code Owner reviews
178+
- ⚠️ Allow force pushes for maintainers only
179+
```
180+
181+
### 企业项目 (严格)
182+
183+
```
184+
- ✅ Require status checks (CI must pass)
185+
- ✅ Require pull request before merging
186+
- ✅ Require 2+ approvals
187+
- ✅ Require conversation resolution
188+
- ✅ Require Code Owner reviews
189+
- ✅ Require signed commits
190+
- ✅ Require linear history
191+
- ✅ Enforce for administrators
192+
```
193+
194+
## 📝 CODEOWNERS 文件 (可选)
195+
196+
创建 `.github/CODEOWNERS` 文件来指定代码所有者:
197+
198+
```
199+
# 默认所有者
200+
* @talkincode
201+
202+
# 核心服务代码
203+
/services/ @talkincode
204+
205+
# 工作流配置
206+
/.github/workflows/ @talkincode
207+
208+
# 文档
209+
*.md @talkincode
210+
```
211+
212+
## 🚨 常见问题
213+
214+
### Q: 如果我是唯一的维护者,还需要分支保护吗?
215+
216+
A: 是的!至少启用 "Require status checks",确保 CI 通过才能合并。这可以防止意外破坏主分支。
217+
218+
### Q: 分支保护后如何提交代码?
219+
220+
A: 通过创建 PR:
221+
222+
```bash
223+
# 1. 创建功能分支
224+
git checkout -b feature/my-feature
225+
226+
# 2. 进行修改并提交
227+
git add .
228+
git commit -m "feat: add new feature"
229+
230+
# 3. 推送分支
231+
git push origin feature/my-feature
232+
233+
# 4. 在 GitHub 创建 PR
234+
# 5. 等待 CI 通过并合并
235+
```
236+
237+
### Q: 紧急修复怎么办?
238+
239+
A: 即使是紧急修复,也应该:
240+
241+
1. 创建 hotfix 分支
242+
2. 快速修复并测试
243+
3. 创建 PR (可以自己审查)
244+
4. 等待 CI 通过
245+
5. 合并
246+
247+
### Q: 可以临时禁用分支保护吗?
248+
249+
A: 不推荐,但管理员可以在设置中临时关闭 "Enforce for administrators"。
250+
251+
## ✅ 验证配置
252+
253+
配置完成后,测试:
254+
255+
```bash
256+
# 尝试直接推送到 main (应该失败)
257+
git checkout main
258+
git commit --allow-empty -m "test"
259+
git push origin main
260+
# 预期: remote: error: GH006: Protected branch update failed
261+
262+
# 正确方式:通过 PR
263+
git checkout -b test-branch-protection
264+
git commit --allow-empty -m "test branch protection"
265+
git push origin test-branch-protection
266+
# 然后在 GitHub 创建 PR
267+
```
268+
269+
## 📊 推荐的分支策略
270+
271+
### Git Flow (推荐用于发布周期的项目)
272+
273+
```
274+
main - 生产环境,受保护
275+
develop - 开发分支,受保护
276+
feature/* - 功能分支
277+
hotfix/* - 紧急修复分支
278+
release/* - 发布分支
279+
```
280+
281+
### GitHub Flow (推荐用于持续部署)
282+
283+
```
284+
main - 生产环境,受保护
285+
feature/* - 功能分支
286+
fix/* - 修复分支
287+
```
288+
289+
### Trunk-Based (推荐用于小团队)
290+
291+
```
292+
main - 主分支,受保护
293+
feature/* - 短期功能分支 (< 2 天)
294+
```
295+
296+
## 🎉 最佳实践
297+
298+
1. **始终通过 PR 合并** - 即使是小改动
299+
2. **保持 PR 小而专注** - 更容易审查
300+
3. **及时审查 PR** - 不要让 PR 积压
301+
4. **使用自动化** - 让 CI 做繁重的工作
302+
5. **编写清晰的 PR 描述** - 使用提供的模板
303+
6. **要求 CI 通过** - 这是最低要求
304+
7. **定期更新保护规则** - 随着项目发展调整
305+
306+
## 📚 相关资源
307+
308+
- [GitHub 分支保护文档](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches)
309+
- [Git Flow 工作流](https://nvie.com/posts/a-successful-git-branching-model/)
310+
- [GitHub Flow](https://guides.github.com/introduction/flow/)
311+
- [Trunk Based Development](https://trunkbaseddevelopment.com/)
312+
313+
---
314+
315+
**快速开始**: 访问 https://github.com/talkincode/hyperliquid-mcp-python/settings/branches 立即配置! 🔒

‎.github/CHECKLIST.md‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,32 @@ open https://github.com/talkincode/hyperliquid-mcp-python/actions
8888
- 代码质量检查应该通过 ✅
8989
- 包构建应该成功 ✅
9090

91-
### 3. 测试发布流程 (可选)
91+
### 3. 配置分支保护 (强烈推荐) 🔒
92+
93+
**为什么需要?**
94+
95+
- 防止直接推送到主分支
96+
- 确保 CI 测试通过才能合并
97+
- 保持代码质量和稳定性
98+
99+
**快速配置:**
100+
101+
1. 访问 https://github.com/talkincode/hyperliquid-mcp-python/settings/branches
102+
2. 点击 "Add branch protection rule"
103+
3. Branch name pattern: `main`
104+
4. 启用以下选项:
105+
- ✅ Require a pull request before merging
106+
- Required approvals: 1
107+
- ✅ Require status checks to pass before merging
108+
- ✅ Require branches to be up to date
109+
- 添加必需检查: `test (3.10)`, `test (3.11)`, `test (3.12)`, `test (3.13)`, `lint`, `build`
110+
- ✅ Require conversation resolution before merging
111+
- ✅ Do not allow bypassing the above settings
112+
5. 点击 "Create"
113+
114+
**详细指南:** 查看 `.github/BRANCH_PROTECTION.md`
115+
116+
### 4. 测试发布流程 (可选)
92117

93118
**创建测试 Release:**
94119

0 commit comments

Comments
 (0)