# EZAI-Go2 Git 提交策略

## 🎯 提交原则

### 应该提交的文件
- ✅ **源代码**: `ezai/*.py`
- ✅ **示例代码**: `examples/*.py`
- ✅ **测试代码**: `tests/*.py`
- ✅ **配置文件**: `setup.py`, `pyproject.toml`, `requirements.txt`
- ✅ **文档文件**: `README.md`, `DEVELOPMENT.md`, `GITHUB_README.md`
- ✅ **许可证**: `LICENSE`
- ✅ **打包清单**: `MANIFEST.in`
- ✅ **版本管理脚本**: `update_version.py`, `quick_update.py`
- ✅ **发布脚本**: `upload.py`

### 绝对不能提交的文件
- ❌ **打包产物**: `dist/`, `*.egg-info/`, `build/`
- ❌ **敏感配置**: `.pypirc`, `.env`, API keys
- ❌ **缓存文件**: `__pycache__/`, `*.pyc`
- ❌ **IDE 配置**: `.vscode/`, `.idea/`
- ❌ **虚拟环境**: `venv/`, `env/`
- ❌ **模型文件**: `*.onnx`, `*.h5`, `*.pth`
- ❌ **数据文件**: `data/`, `datasets/`
- ❌ **日志文件**: `*.log`

## 📝 .gitignore 策略

### 核心排除项
```gitignore
# 打包产物（最重要）
dist/
*.egg-info/
build/
*.egg

# 敏感配置
.pypirc
.env

# Python 缓存
__pycache__/
*.pyc
```

### 开发环境排除
```gitignore
# 虚拟环境
venv/
env/

# IDE 配置
.vscode/
.idea/

# 测试覆盖率
.coverage
.pytest_cache/
```

## 🔄 分支策略

### 主要分支
- **main**: 稳定发布版本
- **develop**: 开发分支（可选）

### 功能分支
- **feature/功能名**: 新功能开发
- **fix/问题描述**: Bug 修复
- **docs/文档更新**: 文档更新
- **release/版本号**: 发布准备

### 分支命名规范
```bash
feature/video-stream-enhancement
fix/go2-connection-issue
docs/update-installation-guide
release/v1.1.0
```

## 📋 提交信息规范

### 格式
```
<类型>(<范围>): <描述>

[可选的详细描述]

[可选的关闭问题]
```

### 类型说明
- **feat**: 新功能
- **fix**: Bug 修复
- **docs**: 文档更新
- **style**: 代码格式化
- **refactor**: 代码重构
- **test**: 测试相关
- **chore**: 构建过程或辅助工具的变动
- **release**: 版本发布

### 示例
```bash
feat(go2): add video stream error handling
fix(camera): resolve image capture timeout issue
docs(readme): update installation instructions
style(ezai): apply black formatting
refactor(ui): simplify widget creation logic
test(go2): add connection test cases
chore(deps): update numpy version constraint
release(v1.0.9): patch release with documentation updates
```

## 🚀 发布流程

### 1. 开发阶段
```bash
# 创建功能分支
git checkout -b feature/new-function

# 开发和提交
git add .
git commit -m "feat(module): add new function"
git push origin feature/new-function
```

### 2. 发布准备
```bash
# 切换到主分支
git checkout main
git pull origin main

# 合并功能分支
git merge feature/new-function

# 更新版本（使用脚本）
python quick_update.py patch

# 提交版本更新
git add .
git commit -m "release(v1.0.10): patch release"
```

### 3. 发布后
```bash
# 推送主分支
git push origin main

# 创建标签
git tag -a v1.0.10 -m "Release version 1.0.10"
git push origin v1.0.10

# 删除功能分支
git branch -d feature/new-function
git push origin --delete feature/new-function
```

## 🔍 代码审查检查点

### 提交前检查
- [ ] 代码格式化 (`black ezai/`)
- [ ] 代码检查 (`flake8 ezai/`)
- [ ] 测试通过 (`pytest tests/`)
- [ ] 文档更新
- [ ] 版本号更新（如需要）
- [ ] 无敏感信息泄露

### 提交信息检查
- [ ] 类型正确
- [ ] 范围明确
- [ ] 描述清晰
- [ ] 关联问题（如有）

## 📊 仓库大小优化

### 定期清理
```bash
# 清理 Git 历史（谨慎使用）
git filter-branch --force --index-filter 'git rm --cached --ignore-unmatch large-file.onnx' --prune-empty --tag-name-filter cat -- --all

# 清理未跟踪文件
git clean -fd
```

### 大文件处理
- 模型文件使用 Git LFS
- 数据文件放在外部存储
- 避免提交二进制文件

## 🛡️ 安全最佳实践

### 敏感信息保护
- `.pypirc` 永远不提交
- API token 使用环境变量
- 密钥使用配置文件模板

### 代码审查
- 所有提交需要代码审查
- 检查硬编码的敏感信息
- 验证依赖安全性

## 📋 常见问题

### Q: 如何处理已提交的大文件？
```bash
# 查找大文件
git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | sed -n 's/^blob //p' | sort --numeric-sort --key=2 | tail -10

# 从历史中移除
git filter-branch --force --index-filter 'git rm --cached --ignore-unmatch large-file' --prune-empty --tag-name-filter cat -- --all
```

### Q: 如何恢复误删的文件？
```bash
# 从暂存区恢复
git restore --staged file.txt

# 从提交历史恢复
git checkout HEAD~1 -- file.txt
```

### Q: 如何撤销提交？
```bash
# 撤销最后一次提交（保留修改）
git reset --soft HEAD~1

# 撤销最后一次提交（丢弃修改）
git reset --hard HEAD~1
```

---

⚠️ **重要提醒**:
- 提交前务必检查 `.gitignore` 配置
- 绝对不要提交 `dist/` 和 `*.egg-info/` 目录
- 使用语义化提交信息
- 定期清理仓库，保持精简