📋 完整操作流程

阶段一：项目准备

1. Fork项目到个人仓库

bash

# 在GitHub网页端操作：
# 1. 访问原始仓库：https://github.com/NodEducation/LLM-X-Season2
# 2. 点击右上角 "Fork" 按钮
# 3. 选择你的个人账户作为目标
# 4. 等待Fork完成

2. 克隆到本地开发环境

bash

# 获取你的Fork仓库URL（在Fork仓库页面点击绿色"Code"按钮）
git clone https://github.com/你的用户名/LLM-X-Season2.git

# 进入项目目录
cd LLM-X-Season2

3. 配置远程仓库关系

bash

# 查看当前远程仓库
git remote -v
# 应该显示：origin → 你的Fork仓库

# 添加上游原始仓库（便于后续同步）
git remote add upstream https://github.com/NodEducation/LLM-X-Season2.git

# 验证远程仓库配置
git remote -v
# 应该显示：
# origin    https://github.com/你的用户名/LLM-X-Season2.git (fetch)
# origin    https://github.com/你的用户名/LLM-X-Season2.git (push)
# upstream  https://github.com/NodEducation/LLM-X-Season2.git (fetch)
# upstream  https://github.com/NodEducation/LLM-X-Season2.git (push)

阶段二：分支管理与开发

4. 创建功能分支

bash

# 永远不要在main/master分支直接开发
git checkout -b 功能描述-你的标识
# 示例：
git checkout -b lesson2-homework-metaphor

5. 开发工作流

bash

# 日常开发循环：
# 1. 编写代码
# 2. 添加更改到暂存区
git add .

# 3. 提交更改（使用规范化的提交信息）
git commit -m "类型(范围): 描述"

# 4. 定期推送到远程
git push -u origin 分支名

提交信息规范：

text

feat: 添加用户认证系统
fix: 修复分页查询错误
docs: 更新API文档
test: 添加用户登录测试
chore: 更新依赖版本

6. 保持分支同步

bash

# 定期从上游main分支获取更新
git fetch upstream

# 合并上游更新到你的分支
git merge upstream/main
# 或者使用rebase（保持历史整洁）
git rebase upstream/main

阶段三：提交准备

7. 最终代码整理

bash

# 检查提交历史
git log --oneline -10

# 检查文件状态
git status

# 如果有多个提交，可以考虑整理提交历史
git rebase -i HEAD~3  # 整理最近3个提交

8. 推送到远程仓库

bash

# 首次推送
git push -u origin 分支名

# 后续更新推送
git push

# 如果需要强制更新（谨慎使用）
git push -f origin 分支名

阶段四：创建Pull Request

9. 在GitHub创建PR

text

1. 访问你的Fork仓库页面
2. 点击 "Pull requests" 标签
3. 点击 "New pull request" 按钮
4. 选择分支对比：
   - base repository: NodEducation/LLM-X-Season2
   - base: main
   - head repository: 你的用户名/LLM-X-Season2
   - compare: 你的功能分支
5. 填写PR信息
6. 点击 "Create pull request"

10. PR信息模板

标题格式：

text

类型: 功能描述 - 你的标识
示例: feat: 完成LLM提示词管理系统 - metaphor

描述模板：

markdown

## 变更描述
简要说明这个PR实现的功能

## 完成的功能清单
- [ ] 功能1描述
- [ ] 功能2描述
- [ ] 功能3描述

## 测试验证
- [ ] 本地测试通过
- [ ] Docker构建成功
- [ ] API端点测试完成

## 技术细节
- 使用的技术栈
- 数据库变更
- 配置文件更新

## 相关问题
关联的Issue编号（如果有）

阶段五：PR后续处理

11. 处理代码审查意见

bash

# 根据审查意见修改代码后
git add .
git commit -m "fix: 根据审查意见修复问题"
git push origin 分支名
# PR会自动更新

12. 解决合并冲突

bash

# 如果PR出现冲突
git fetch upstream
git merge upstream/main
# 手动解决冲突文件
git add .
git commit -m "fix: 解决合并冲突"
git push origin 分支名

⚠️ 关键注意事项

Git操作安全准则

1. 分支保护：永远不要在main分支直接开发

2. 提交前检查：每次提交前运行 git status 和 git diff

3. 备份重要更改：重要功能开发前创建备份分支

4. 谨慎使用强制推送：git push -f 可能丢失历史

文件管理规范

1. 避免嵌套Git仓库：确保子文件夹没有 .git 目录

2. 正确配置.gitignore：排除编译文件、环境变量等

3. 环境变量安全：不要提交 .env 文件，使用 .env.example

依赖管理

1. 固定版本：在生产环境中固定依赖版本

2. 定期更新：定期检查并更新依赖版本

3. 冲突解决：注意依赖之间的版本兼容性

🚀 流程优化建议

1. 开发前准备优化

bash

# 创建开发准备脚本 setup-dev.sh
#!/bin/bash
git clone $1
cd $(basename $1 .git)
git remote add upstream 原始仓库URL
git checkout -b feature-branch
echo "开发环境准备完成"

2. 提交前自动检查

bash

# 创建预提交钩子 .git/hooks/pre-commit
#!/bin/bash
# 运行测试
python -m pytest tests/
# 代码格式检查
flake8 app/
# 确保没有敏感信息
git diff --cached --name-only | grep -E '(.env|config.py)' && echo "警告：检查敏感文件" && exit 1

3. 分支命名规范

text

类型/描述-标识
示例：
feat/user-authentication-john
fix/pagination-bug-smith
docs/api-update-lee

4. PR模板标准化

在仓库根目录创建 .github/pull_request_template.md：

markdown

## 变更类型
- [ ] 新功能
- [ ] Bug修复
- [ ] 文档更新
- [ ] 重构
- [ ] 其他

## 描述
<!-- 详细描述这个PR -->

## 测试清单
- [ ] 本地测试通过
- [ ] 集成测试通过
- [ ] 文档已更新

## 截图（如适用）
<!-- 添加UI变更的截图 -->

## 相关Issue
<!-- 关联的Issue编号 -->

5. 自动化工作流

在 .github/workflows/ci.yml 中配置：

yaml

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run tests
        run: |
          docker-compose up -d
          pytest tests/

🔧 故障排除指南

常见问题及解决方案

1. PR显示"没有共同提交历史"

bash

# 解决方案：
git fetch upstream
git reset --hard upstream/main
# 重新添加文件并提交
git add .
git commit -m "feat: 功能描述"
git push -f origin 分支名

2. 依赖版本冲突

bash

# 检查冲突
pip check
# 更新requirements.txt
pip freeze > requirements.txt
# 或使用兼容版本范围

3. 子模块问题

bash

# 移除嵌套Git仓库
git rm --cached 文件夹路径
rm -rf 文件夹路径/.git
git add 文件夹路径/

4. 认证失败

bash

# 使用Personal Access Token
git clone https://用户名:token@github.com/用户名/仓库名.git

📊 最佳实践总结

开发阶段

1. 小步提交：每个功能点单独提交

2. 描述清晰：提交信息说明"做了什么"和"为什么"

3. 定期同步：每天从上游main分支拉取更新

提交阶段

1. 自我审查：提交前检查代码质量

2. 测试验证：确保所有功能正常

3. 文档更新：代码变更伴随文档更新

协作阶段

1. 及时响应：快速处理审查意见

2. 沟通清晰：在PR中说明复杂决策

3. 持续学习：从每次PR中总结经验