From 7bae818a09b63a1654094a1da2ae92cc5bd58412 Mon Sep 17 00:00:00 2001 From: SkyLi Date: Tue, 14 Apr 2026 09:27:46 +0800 Subject: [PATCH] =?UTF-8?q?=E9=87=8D=E6=9E=84=20Wiki=20=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Home 页面改为主导航，链接到各主要页面 - 开发环境配置指南拆分为5个独立文件 - 开发规范融入开发流程（含 rebase/merge 策略、IDE 注意提示） --- ...%83%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.md | 403 ------------------ Home.md | 17 +- 开发环境配置指南/1-SSH密钥配置.md | 72 ++++ 开发环境配置指南/2-连接验证.md | 38 ++ 开发环境配置指南/3-仓库拉取.md | 34 ++ 开发环境配置指南/4-开发流程.md | 156 +++++++ 开发环境配置指南/5-子模块更新.md | 85 ++++ 7 files changed, 401 insertions(+), 404 deletions(-) delete mode 100644 %E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.md create mode 100644 开发环境配置指南/1-SSH密钥配置.md create mode 100644 开发环境配置指南/2-连接验证.md create mode 100644 开发环境配置指南/3-仓库拉取.md create mode 100644 开发环境配置指南/4-开发流程.md create mode 100644 开发环境配置指南/5-子模块更新.md diff --git a/%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.md b/%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.md deleted file mode 100644 index 336e494..0000000 --- a/%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.md +++ /dev/null @@ -1,403 +0,0 @@ -# 新成员开发环境配置指南 - -> 本文档面向团队新成员，指导如何配置开发环境、拉取代码并进行协作开发。 - ---- - -## 目录 - -1. [创建 SSH 公私钥对](#1-创建-ssh-公私钥对) -2. [在 Gitea 上添加公钥](#2-在-gitea-上添加公钥) -3. [验证 SSH 连接和签名验证](#3-验证-ssh-连接和签名验证) -4. [拉取主仓库及子模块](#4-拉取主仓库及子模块) -5. [开发流程](#5-开发流程) -6. [子模块更新说明](#6-子模块更新说明) - ---- - -## 1. 创建 SSH 公私钥对 - -如果没有现成的 SSH 密钥对，需要先生成一对。 - -### 生成命令 - -```bash -ssh-keygen -t ed25519 -C "your_email@example.com" -``` - -**参数说明：** -- `-t ed25519`：使用 Ed25519 算法（推荐，比 RSA 更安全、更短） -- `-C "your_email@example.com"`：注释，通常填你的邮箱，便于识别 - -### 交互提示 - -``` -Generating public/private ed25519 key pair. -Enter file in which to save key (/home/you/.ssh/id_ed25519): # 直接回车使用默认路径 -Enter passphrase (empty for no passphrase): # 输入密码短语，建议设置，若不设置则直接回车 -Enter same passphrase again: # 确认密码短语，若不设置则直接回车 -``` - -> **注意**：密码短语是你对私钥的额外保护，即使他人拿到私钥文件，没有密码也无法使用。请妥善保管，不要遗忘。 - -### 生成的文件 - -| 文件 | 说明 | -|------|------| -| `~/.ssh/id_ed25519` | 私钥（**不要泄露**） | -| `~/.ssh/id_ed25519.pub` | 公钥（需要填到 Gitea） | - -### 确认文件存在 - -```bash -ls -la ~/.ssh/id_ed25519* -``` - ---- - -## 2. 在 Gitea 上添加公钥 - -### 步骤 - -1. **获取公钥内容** - - ```bash - cat ~/.ssh/id_ed25519.pub - ``` - - 输出类似于： - ``` - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBLABELOCATED/ahKwj98dsfsaf+ASDNo7your_email@example.com - ``` - -2. **登录 Gitea** - - 打开团队 Gitea 地址（如 `https://gitea.your-team.com`），登录你的账号。 - -3. **添加公钥** - - - 点击右上角头像 → **设置（Settings）** - - 左侧菜单找到 **SSH 密钥（SSH Keys）** - - 点击 **添加密钥（Add Key）** - - 填写： - - **标题（Title）**：给密钥起个名字，如 `我的笔记本` 或 `Desktop-PC` - - **密钥（Key）**：粘贴上一步 `cat` 输出的完整内容 - - 点击 **添加（Add Key）** - ---- - -## 3. 签名验证和验证 SSH 连接 - -### 签名验证 - -点开网页上的签名验证，在本地执行提示中的指令，形如： - -```bash -echo -n 'de8a6d7337894d506afe8a30759c54fe2c9afc0570f46891be94bf1f544cde43' | ssh-keygen -Y sign -n gitea -f ~/.ssh/id_ed25519 -``` - -输出示例： - -``` ------BEGIN SSH SIGNATURE----- -U1NIU0lHAAAAA...（中间是一长串字符）... ------END SSH SIGNATURE----- -``` - -将输出粘贴到网页中，点击验证即可。 - -这是因为，当前服务器已经拿到了你的公钥，服务器要确定你确实拥有对应的私钥，因此会给出一个随机字符串，让你运行以上命令使用你的私钥对这个字符串进行加密， -服务器拿到你的密文内容后，使用公钥对密文内容解密，将解密内容与一开始生成的字符串对比，如果一致，就说明你确实拥有私钥。 - -### 测试连接 - -```bash -ssh -T git@gitea.your-team.com -``` - -替换 `gitea.your-team.com` 为你们的 Gitea 域名。 - -**成功输出示例：** - -``` -Hi your_username! You've successfully authenticated, but Gitea does not provide shell access. -``` - -## 4. 拉取主仓库及子模块 - -### 克隆仓库 - -**必须使用 `--recursive` 参数**，否则子模块目录会是空的： - -```bash -git clone --recursive git@gitea.your-team.com:your-team/auto-aim-mobile-bot.git -``` - -### 如果克隆时忘记 `--recursive` - -可以单独初始化子模块： - -```bash -# 进入仓库目录 -cd auto-aim-mobile-bot - -# 初始化并更新子模块 -git submodule update --init --recursive -``` - -### 验证克隆结果 - -```bash -# 查看子模块状态 -git submodule status - -# 预期输出类似： -# 917f5b74eb6b1e8d7bce57fa2274bb0574f336b6 modules/chassis (heads/main) -# f9e81d6e04c2a38e43b78961aea2686aa121d960 modules/gimbal (heads/main) -``` - ---- - -## 5. 开发流程 - -### 5.1 创建新分支 - -**根据你要修改的目标，选择在对应仓库创建分支：** - -- **修改子模块**（`modules/chassis` 或 `modules/gimbal`）： - ```bash - cd modules/chassis # 进入子模块目录 - git checkout -b feature/your-feature-name - ``` -- **修改主仓库**（配置、文档等）： - ```bash - git checkout -b feature/your-feature-name # 在主仓库根目录执行 - ``` - -### 5.2 在子模块中开发 - -**进入子模块目录：** - -```bash -cd modules/chassis # 或 cd modules/gimbal -``` - -**创建子模块分支并开发：** - -```bash -git checkout -b feature/your-feature-name -# ... 进行开发，编写代码 ... -git add . -git commit -m "前缀: 描述你的改动" [-m "第一行" -m "第二行"] -# 多行内容推荐直接使用： -git commit -``` - -**推荐 commit message 格式：** - -``` -<类型>: <简短描述> - -[可选的详细说明] -``` - -**常用类型：** - -| 类型 | 含义 | -|------|------| -| `feat` | 新功能 | -| `fix` | 修复 bug | -| `docs` | 文档改动 | -| `style` | 代码格式（不影响功能） | -| `refactor` | 重构（不是修复也不是新功能） | -| `perf` | 性能优化 | -| `test` | 添加/修改测试 | -| `chore` | 构建/工具变动 | - -**示例：** - -``` -feat: 添加云台视觉识别模块 - -- 集成 YOLOv8 模型推理 -- 实现目标框坐标解算 -``` - -> 子模块和主仓库的 commit 均遵循此格式。 - -### 5.3 保持子模块代码最新 - -开发子模块时，**每次开始工作前**建议拉取最新代码，避免合并冲突： - -```bash -cd modules/chassis # 或 modules/gimbal -git checkout main -git pull origin main -git checkout feature/your-feature-name -git merge main # 或 git rebase main -``` - -或在主仓库一次性更新所有子模块到各自主分支的最新提交： - -```bash -git submodule update --remote --recursive -``` - -> **注意**：`--remote` 默认更新到各子模块的 `main` 分支。如果子模块有其他开发分支（如 `dev`），需要先在子模块内切换到对应分支，再单独 `git pull`。 - -### 5.4 提交主仓库（仅在需要时） - -> **重要提示**： -> -> 主仓库中记录的是**子模块当前指向的提交指针**。请**不要频繁提交**这类更新——每次子模块有新提交就提 PR 会造成大量噪音。 -> -> **只在以下情况才提交主仓库的子模块指针更新：** -> - 子模块有重大版本更新 -> - 需要同步所有成员的子模块状态 -> - release 准备阶段 - -**提交主仓库：** - -```bash -cd auto-aim-mobile-bot -git add modules/chassis modules/gimbal -git commit -m "chore: 更新子模块到最新版本" -``` - -### 5.5 推送分支 - -**推送子模块（如在子模块中开发）：** - -> 推送前请先确保你当前处于**子模块目录内**： - -```bash -cd modules/chassis # 或 modules/gimbal -git push -u origin feature/your-feature-name -``` - -> 注意：子模块的远程是独立的，push 操作不影响主仓库。推送后去对应的**子模块仓库**页面创建 PR。 - -**推送主仓库分支：** - -> 在主仓库**根目录**执行： - -```bash -git push -u origin feature/your-feature-name -``` - -### 5.6 提 Pull Request - -1. 在 Gitea 上打开对应的仓库页面 -2. 点击 **创建 Pull Request**（或 Compare & pull request） -3. 选择： - - **base branch**：合并目标分支（如 `main`） - - **compare branch**：你的开发分支（如 `feature/your-feature-name`） -4. 填写 PR 标题和描述，说明改动内容和目的 -5. 指定 Reviewer（如果有） -6. 点击 **创建 Pull Request** - -### 5.7 Review 通过后合并 - -- PR 通过 Review 后，点击 **Merge** -- 合并后**删除已合并的分支**（保持仓库整洁） - ---- - -## 6. 子模块更新说明 - -### 工作流程图 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ 主仓库 (main) │ -│ 仅记录子模块指针，不频繁更新（仅大版本/发布前更新） │ -└─────────────────────────────────────────────────────────────┘ - ▲ ▲ ▲ - │ │ │ - │ submodule │ submodule │ submodule - │ update │ update │ update - │ --remote │ --remote │ --remote - │ │ │ -┌───────────┐ ┌───────────┐ ┌───────────┐ -│ chassis │ │ gimbal │ │ 其他模块 │ -│ (子模块) │ │ (子模块) │ │ (子模块) │ -│ 独立分支 │ │ 独立分支 │ │ 独立分支 │ -│ 独立PR │ │ 独立PR │ │ 独立PR │ -└───────────┘ └───────────┘ └───────────┘ -``` - -### 子模块独立开发的好处 - -- 各模块可以独立迭代，不影响其他模块 -- 子模块的 PR 不会触发主仓库不必要的构建 -- 团队可以并行开发多个功能 - -### 推荐做法 - -| 场景 | 操作位置 | -|------|---------| -| 修改 `modules/chassis` 代码 | 在 `modules/chassis` 目录内创建分支、提 PR | -| 修改 `modules/gimbal` 代码 | 在 `modules/gimbal` 目录内创建分支、提 PR | -| 修改主仓库配置/文档 | 在主仓库创建分支、提 PR | -| 更新子模块指针（仅大版本） | 在主仓库创建分支、提 PR | - ---- - -## 常见问题 - -### Q: 克隆时提示 `Permission denied (publickey)`？ - -检查： -1. 公钥是否正确添加到 Gitea -2. 私钥文件是否存在且权限正确（`chmod 600 ~/.ssh/id_ed25519`） -3. SSH 代理是否加载了私钥 - -### Q: 子模块目录是空的？ - -使用了 `git clone` 但没有加 `--recursive`，或子模块未初始化。运行： - -```bash -git submodule update --init --recursive -``` - -### Q: 如何查看子模块的远程地址？ - -```bash -git submodule foreach 'git remote -v' -``` - -### Q: 子模块当前在哪个分支？ - -进入子模块目录查看： - -```bash -cd modules/chassis -git branch -``` - -或在主仓库内查看所有子模块的当前分支状态： - -```bash -git submodule foreach 'git branch --show-current' -``` - -### Q: 能否在主仓库目录内直接操作子模块？ - -可以，使用 `git -C` 语法： - -```bash -git -C modules/chassis status -git -C modules/chassis checkout main -git -C modules/chassis pull origin main -``` - -这与先 `cd` 再执行效果相同。 - -### Q: 推送代码时需要同时推送主仓库和子模块吗？ - -不需要。**子模块和主仓库是独立的仓库**，各自有独立的提交历史和分支体系。 - -- 在子模块中开发 → 在子模块仓库提 PR → 合并到子模块的 main -- 在主仓库修改配置文件/文档 → 在主仓库提 PR → 合并到主仓库的 main - -**只有当你确实需要将子模块的指针更新同步给其他成员时**，才需要更新并推送主仓库（如第 5.4 节所述的大版本场景）。 diff --git a/Home.md b/Home.md index 54559bf..be8c989 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,16 @@ -用于存放项目选型介绍、技术参数、技术路线等，选择不同的页面查看相应内容。 \ No newline at end of file +# Auto-Aim Mobile Bot Wiki + +项目技术文档中心 + +## 开发入门 + +- [开发环境配置指南](./开发环境配置指南/1-SSH密钥配置.md) + - [SSH 密钥配置](./开发环境配置指南/1-SSH密钥配置.md) + - [连接验证](./开发环境配置指南/2-连接验证.md) + - [仓库拉取](./开发环境配置指南/3-仓库拉取.md) + - [开发流程](./开发环境配置指南/4-开发流程.md) + - [子模块更新](./开发环境配置指南/5-子模块更新.md) + +## 技术文档 + +- [硬件技术参数](./硬件技术参数.md) diff --git a/开发环境配置指南/1-SSH密钥配置.md b/开发环境配置指南/1-SSH密钥配置.md new file mode 100644 index 0000000..5820739 --- /dev/null +++ b/开发环境配置指南/1-SSH密钥配置.md @@ -0,0 +1,72 @@ +# SSH 密钥配置 + +本文介绍如何创建 SSH 公私钥对并添加到 Gitea。 + +## 1. 创建 SSH 公私钥对 + +如果没有现成的 SSH 密钥对，需要先生成一对。 + +### 生成命令 + +```bash +ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +**参数说明：** +- `-t ed25519`：使用 Ed25519 算法（推荐，比 RSA 更安全、更短） +- `-C "your_email@example.com"`：注释，通常填你的邮箱，便于识别 + +### 交互提示 + +``` +Generating public/private ed25519 key pair. +Enter file in which to save key (/home/you/.ssh/id_ed25519): # 直接回车使用默认路径 +Enter passphrase (empty for no passphrase): # 输入密码短语，建议设置，若不设置则直接回车 +Enter same passphrase again: # 确认密码短语，若不设置则直接回车 +``` + +> **注意**：密码短语是你对私钥的额外保护，即使他人拿到私钥文件，没有密码也无法使用。请妥善保管，不要遗忘。 + +### 生成的文件 + +| 文件 | 说明 | +|------|------| +| `~/.ssh/id_ed25519` | 私钥（**不要泄露**） | +| `~/.ssh/id_ed25519.pub` | 公钥（需要填到 Gitea） | + +### 确认文件存在 + +```bash +ls -la ~/.ssh/id_ed25519* +``` + +--- + +## 2. 在 Gitea 上添加公钥 + +### 步骤 + +1. **获取公钥内容** + + ```bash + cat ~/.ssh/id_ed25519.pub + ``` + + 输出类似于： + ``` + ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBLABELOCATED/ahKwj98dsfsaf+ASDNo7your_email@example.com + ``` + +2. **登录 Gitea** + + 打开团队 Gitea 地址（如 `https://gitea.your-team.com`），登录你的账号。 + +3. **添加公钥** + + - 点击右上角头像 → **设置（Settings）** + - 左侧菜单找到 **SSH 密钥（SSH Keys）** + - 点击 **添加密钥（Add Key）** + - 填写： + - **标题（Title）**：给密钥起个名字，如 `我的笔记本` 或 `Desktop-PC` + - **密钥（Key）**：粘贴上一步 `cat` 输出的完整内容 + - 点击 **添加（Add Key）** diff --git a/开发环境配置指南/2-连接验证.md b/开发环境配置指南/2-连接验证.md new file mode 100644 index 0000000..9521d1f --- /dev/null +++ b/开发环境配置指南/2-连接验证.md @@ -0,0 +1,38 @@ +# SSH 连接与签名验证 + +本文介绍如何在 Gitea 上完成签名验证以及测试 SSH 连接。 + +## 签名验证 + +点开网页上的签名验证，在本地执行提示中的指令，形如： + +```bash +echo -n 'de8a6d7337894d506afe8a30759c54fe2c9afc0570f46891be94bf1f544cde43' | ssh-keygen -Y sign -n gitea -f ~/.ssh/id_ed25519 +``` + +输出示例： + +``` +-----BEGIN SSH SIGNATURE----- +U1NIU0lHAAAAA...（中间是一长串字符）... +-----END SSH SIGNATURE----- +``` + +将输出粘贴到网页中，点击验证即可。 + +这是因为，当前服务器已经拿到了你的公钥，服务器要确定你确实拥有对应的私钥，因此会给出一个随机字符串，让你运行以上命令使用你的私钥对这个字符串进行加密， +服务器拿到你的密文内容后，使用公钥对密文内容解密，将解密内容与一开始生成的字符串对比，如果一致，就说明你确实拥有私钥。 + +## 测试 SSH 连接 + +```bash +ssh -T git@gitea.your-team.com +``` + +替换 `gitea.your-team.com` 为你们的 Gitea 域名。 + +**成功输出示例：** + +``` +Hi your_username! You've successfully authenticated, but Gitea does not provide shell access. +``` diff --git a/开发环境配置指南/3-仓库拉取.md b/开发环境配置指南/3-仓库拉取.md new file mode 100644 index 0000000..8e333ee --- /dev/null +++ b/开发环境配置指南/3-仓库拉取.md @@ -0,0 +1,34 @@ +# 仓库拉取 + +本文介绍如何克隆主仓库及其子模块。 + +## 克隆仓库 + +**必须使用 `--recursive` 参数**，否则子模块目录会是空的： + +```bash +git clone --recursive git@gitea.your-team.com:your-team/auto-aim-mobile-bot.git +``` + +## 如果克隆时忘记 `--recursive` + +可以单独初始化子模块： + +```bash +# 进入仓库目录 +cd auto-aim-mobile-bot + +# 初始化并更新子模块 +git submodule update --init --recursive +``` + +## 验证克隆结果 + +```bash +# 查看子模块状态 +git submodule status + +# 预期输出类似： +# 917f5b74eb6b1e8d7bce57fa2274bb0574f336b6 modules/chassis (heads/main) +# f9e81d6e04c2a38e43b78961aea2686aa121d960 modules/gimbal (heads/main) +``` diff --git a/开发环境配置指南/4-开发流程.md b/开发环境配置指南/4-开发流程.md new file mode 100644 index 0000000..0566cc1 --- /dev/null +++ b/开发环境配置指南/4-开发流程.md @@ -0,0 +1,156 @@ +# 开发流程 + +本文介绍子模块开发的标准流程，包括分支管理、代码提交、推送和 Pull Request。 + +## 开发规范 + +> **注意**：为保证良好的开发体验，确保 IDE 正确识别项目结构，请以**子模块（子仓库）目录**作为工作空间根目录打开，而非主仓库根目录。 + +### Git 工作流 + +- **跟进最新代码**：功能分支使用 `git rebase main` 保持线性历史 +- **合并策略**：PR 合并采用 `merge` 方式，保留历史分支轨迹 +- **分支清理**：合并后删除已合并的分支 + +--- + +## 创建新分支 + +**根据你要修改的目标，选择在对应仓库创建分支：** + +- **修改子模块**（`modules/chassis` 或 `modules/gimbal`）： + ```bash + cd modules/chassis # 进入子模块目录 + git checkout -b feature/your-feature-name + ``` +- **修改主仓库**（配置、文档等）： + ```bash + git checkout -b feature/your-feature-name # 在主仓库根目录执行 + ``` + +## 在子模块中开发 + +**进入子模块目录：** + +```bash +cd modules/chassis # 或 cd modules/gimbal +``` + +**创建子模块分支并开发：** + +```bash +git checkout -b feature/your-feature-name +# ... 进行开发，编写代码 ... +git add . +git commit -m "前缀: 描述你的改动" [-m "第一行" -m "第二行"] +# 多行内容推荐直接使用： +git commit +``` + +**推荐 commit message 格式：** + +``` +<类型>: <简短描述> + +[可选的详细说明] +``` + +**常用类型：** + +| 类型 | 含义 | +|------|------| +| `feat` | 新功能 | +| `fix` | 修复 bug | +| `docs` | 文档改动 | +| `style` | 代码格式（不影响功能） | +| `refactor` | 重构（不是修复也不是新功能） | +| `perf` | 性能优化 | +| `test` | 添加/修改测试 | +| `chore` | 构建/工具变动 | + +**示例：** + +``` +feat: 添加云台视觉识别模块 + +- 集成 YOLOv8 模型推理 +- 实现目标框坐标解算 +``` + +> 子模块和主仓库的 commit 均遵循此格式。 + +## 保持子模块代码最新 + +开发子模块时，**每次开始工作前**建议使用 rebase 拉取最新代码： + +```bash +cd modules/chassis # 或 modules/gimbal +git checkout main +git pull origin main +git checkout feature/your-feature-name +git rebase main # 保持线性历史 +``` + +或在主仓库一次性更新所有子模块到各自主分支的最新提交： + +```bash +git submodule update --remote --recursive +``` + +> **注意**：`--remote` 默认更新到各子模块的 `main` 分支。如果子模块有其他开发分支（如 `dev`），需要先在子模块内切换到对应分支，再单独 `git pull`。 + +## 提交主仓库（仅在需要时） + +> **重要提示**： +> +> 主仓库中记录的是**子模块当前指向的提交指针**。请**不要频繁提交**这类更新——每次子模块有新提交就提 PR 会造成大量噪音。 +> +> **只在以下情况才提交主仓库的子模块指针更新：** +> - 子模块有重大版本更新 +> - 需要同步所有成员的子模块状态 +> - release 准备阶段 + +**提交主仓库：** + +```bash +cd auto-aim-mobile-bot +git add modules/chassis modules/gimbal +git commit -m "chore: 更新子模块到最新版本" +``` + +## 推送分支 + +**推送子模块（如在子模块中开发）：** + +> 推送前请先确保你当前处于**子模块目录内**： + +```bash +cd modules/chassis # 或 modules/gimbal +git push -u origin feature/your-feature-name +``` + +> 注意：子模块的远程是独立的，push 操作不影响主仓库。推送后去对应的**子模块仓库**页面创建 PR。 + +**推送主仓库分支：** + +> 在主仓库**根目录**执行： + +```bash +git push -u origin feature/your-feature-name +``` + +## 提 Pull Request + +1. 在 Gitea 上打开对应的仓库页面 +2. 点击 **创建 Pull Request**（或 Compare & pull request） +3. 选择： + - **base branch**：合并目标分支（如 `main`） + - **compare branch**：你的开发分支（如 `feature/your-feature-name`） +4. 填写 PR 标题和描述，说明改动内容和目的 +5. 指定 **Project(项目)** +6. 点击 **创建 Pull Request** + +## Review 通过后合并 + +- PR 通过 Review 后，点击 **Merge** +- 合并后**删除已合并的分支**（保持仓库整洁） diff --git a/开发环境配置指南/5-子模块更新.md b/开发环境配置指南/5-子模块更新.md new file mode 100644 index 0000000..fb80d55 --- /dev/null +++ b/开发环境配置指南/5-子模块更新.md @@ -0,0 +1,85 @@ +# 子模块更新说明 + +本文介绍子模块的独立开发模式及推荐工作流程。 + +## 工作流程图 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 主仓库 (main) │ +│ 仅记录子模块指针，不频繁更新（仅大版本/发布前更新） │ +└─────────────────────────────────────────────────────────────┘ + ▲ ▲ ▲ + │ │ │ + │ submodule │ submodule │ submodule + │ update │ update │ update + │ --remote │ --remote │ --remote + │ │ │ +┌───────────┐ ┌───────────┐ ┌───────────┐ +│ chassis │ │ gimbal │ │ 其他模块 │ +│ (子模块) │ │ (子模块) │ │ (子模块) │ +│ 独立分支 │ │ 独立分支 │ │ 独立分支 │ +│ 独立PR │ │ 独立PR │ │ 独立PR │ +└───────────┘ └───────────┘ └───────────┘ +``` + +## 子模块独立开发的好处 + +- 各模块可以独立迭代，不影响其他模块 +- 子模块的 PR 不会触发主仓库不必要的构建 +- 团队可以并行开发多个功能 + +## 推荐做法 + +| 场景 | 操作位置 | +|------|---------| +| 修改 `modules/chassis` 代码 | 在 `modules/chassis` 目录内创建分支、提 PR | +| 修改 `modules/gimbal` 代码 | 在 `modules/gimbal` 目录内创建分支、提 PR | +| 修改主仓库配置/文档 | 在主仓库创建分支、提 PR | +| 更新子模块指针（仅大版本） | 在主仓库创建分支、提 PR | + +--- + +## 常见问题 + +### Q: 克隆时提示 `Permission denied (publickey)`？ + +检查： +1. 公钥是否正确添加到 Gitea +2. 私钥文件是否存在且权限正确（`chmod 600 ~/.ssh/id_ed25519`） +3. SSH 代理是否加载了私钥 + +### Q: 子模块目录是空的？ + +使用了 `git clone` 但没有加 `--recursive`，或子模块未初始化。运行： + +```bash +git submodule update --init --recursive +``` + +### Q: 如何查看子模块的远程地址？ + +```bash +git submodule foreach 'git remote -v' +``` + +### Q: 能否在主仓库目录内直接操作子模块？ + +可以，使用 `git -C` 语法： + +```bash +git -C modules/chassis status +git -C modules/chassis checkout main +git -C modules/chassis pull origin main +``` + +这与先 `cd` 再执行效果相同。 + +### Q: 推送代码时需要同时推送主仓库和子模块吗？ + +不需要。**子模块和主仓库是独立的仓库**，各自有独立的提交历史和分支体系。 + +- 在子模块中开发 → 在子模块仓库提 PR → 合并到子模块的 main +- 在主仓库修改配置文件/文档 → 在主仓库提 PR → 合并到主仓库的 main + +**只有当你确实需要将子模块的指针更新同步给其他成员时**，才需要更新并推送主仓库（如第 4 节所述的大版本场景）。