277 lines
7.1 KiB
Markdown
277 lines
7.1 KiB
Markdown
# 文件组织规范
|
||
|
||
本文档定义了AGV路径跟踪项目的文件组织规范，用于管理bug修复、程序更新和版本归档。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
agv_path_tracking/
|
||
├── archives/ # 归档目录
|
||
│ ├── bug_fixes/ # Bug修复归档
|
||
│ │ └── YYYYMMDD_bug名称/ # 按日期和bug名称组织
|
||
│ │ ├── code/ # 修复的代码文件
|
||
│ │ ├── docs/ # 相关文档
|
||
│ │ └── tests/ # 测试文件
|
||
│ ├── updates/ # 功能更新归档
|
||
│ │ └── YYYYMMDD_功能名称/ # 按日期和功能名称组织
|
||
│ │ ├── code/ # 新增/修改的代码
|
||
│ │ ├── docs/ # 更新文档
|
||
│ │ └── tests/ # 测试文件
|
||
│ └── versions/ # 版本归档
|
||
│ └── vX.Y.Z/ # 按版本号组织
|
||
│ ├── release_notes.md
|
||
│ └── backup/ # 完整代码备份
|
||
├── docs/ # 项目文档
|
||
│ ├── fixes/ # Bug修复文档（当前）
|
||
│ ├── updates/ # 功能更新文档（当前）
|
||
│ ├── guides/ # 使用指南
|
||
│ └── protocol/ # 协议文档
|
||
├── src/ # 源代码（主工作目录）
|
||
├── include/ # 头文件（主工作目录）
|
||
└── examples/ # 示例代码（主工作目录）
|
||
```
|
||
|
||
## 命名规范
|
||
|
||
### 1. Bug修复命名
|
||
- **文件夹命名**: `YYYYMMDD_bug描述`
|
||
- 例如: `20251115_fix_path_tracking_error`
|
||
- **文件命名**: 保持原有文件名，或添加`_fixed`后缀
|
||
- 例如: `path_tracker_fixed.cpp`
|
||
|
||
### 2. 功能更新命名
|
||
- **文件夹命名**: `YYYYMMDD_功能描述`
|
||
- 例如: `20251115_add_adaptive_lookahead`
|
||
- **文件命名**: 清晰描述功能
|
||
- 例如: `adaptive_lookahead.cpp`
|
||
|
||
### 3. 文档命名
|
||
- **Bug修复文档**: `BUG_描述_日期.md`
|
||
- 例如: `BUG_path_tracking_error_20251115.md`
|
||
- **更新文档**: `UPDATE_功能描述_日期.md`
|
||
- 例如: `UPDATE_adaptive_lookahead_20251115.md`
|
||
|
||
## 工作流程
|
||
|
||
### Bug修复流程
|
||
|
||
1. **创建工作目录**
|
||
```bash
|
||
mkdir -p archives/bug_fixes/YYYYMMDD_bug名称/{code,docs,tests}
|
||
```
|
||
|
||
2. **在主代码目录进行修复**
|
||
- 在 `src/`, `include/` 等目录直接修复bug
|
||
- 及时提交git commit
|
||
|
||
3. **归档修复**
|
||
- 将修复的文件副本保存到 `archives/bug_fixes/YYYYMMDD_bug名称/code/`
|
||
- 创建修复文档保存到 `archives/bug_fixes/YYYYMMDD_bug名称/docs/`
|
||
- 同时在 `docs/fixes/` 创建文档副本供快速查阅
|
||
|
||
4. **文档内容应包含**
|
||
- Bug描述和复现步骤
|
||
- 根本原因分析
|
||
- 修复方案说明
|
||
- 修改的文件列表
|
||
- 测试验证结果
|
||
- 相关的git commit ID
|
||
|
||
### 功能更新流程
|
||
|
||
1. **创建工作目录**
|
||
```bash
|
||
mkdir -p archives/updates/YYYYMMDD_功能名称/{code,docs,tests}
|
||
```
|
||
|
||
2. **在主代码目录进行开发**
|
||
- 在 `src/`, `include/` 等目录添加新功能
|
||
- 及时提交git commit
|
||
|
||
3. **归档更新**
|
||
- 将新增/修改的文件副本保存到 `archives/updates/YYYYMMDD_功能名称/code/`
|
||
- 创建更新文档保存到 `archives/updates/YYYYMMDD_功能名称/docs/`
|
||
- 同时在 `docs/updates/` 创建文档副本供快速查阅
|
||
|
||
4. **文档内容应包含**
|
||
- 功能需求描述
|
||
- 设计方案
|
||
- 实现细节
|
||
- API文档（如有）
|
||
- 使用示例
|
||
- 测试结果
|
||
- 相关的git commit ID
|
||
|
||
### 版本发布流程
|
||
|
||
1. **创建版本目录**
|
||
```bash
|
||
mkdir -p archives/versions/vX.Y.Z/backup
|
||
```
|
||
|
||
2. **准备发布**
|
||
- 更新版本号
|
||
- 编写 `release_notes.md`
|
||
- 汇总本版本所有bug修复和功能更新
|
||
|
||
3. **创建备份**
|
||
- 可选：将完整代码打包到 `archives/versions/vX.Y.Z/backup/`
|
||
- 创建git tag
|
||
|
||
4. **发布说明应包含**
|
||
- 版本号和发布日期
|
||
- 新增功能列表
|
||
- Bug修复列表
|
||
- 重大变更说明
|
||
- 升级指南（如需要）
|
||
|
||
## 文档模板
|
||
|
||
### Bug修复文档模板
|
||
|
||
```markdown
|
||
# Bug修复: [Bug简短描述]
|
||
|
||
**日期**: YYYY-MM-DD
|
||
**修复者**: [姓名]
|
||
**相关Issue**: #[编号]（如有）
|
||
|
||
## Bug描述
|
||
[详细描述bug的表现]
|
||
|
||
## 复现步骤
|
||
1. [步骤1]
|
||
2. [步骤2]
|
||
3. [观察到的错误行为]
|
||
|
||
## 根本原因
|
||
[分析bug的根本原因]
|
||
|
||
## 修复方案
|
||
[描述如何修复这个bug]
|
||
|
||
## 修改文件
|
||
- `src/xxx.cpp` - [修改说明]
|
||
- `include/xxx.h` - [修改说明]
|
||
|
||
## 测试验证
|
||
[描述如何测试验证修复有效]
|
||
|
||
## Git Commit
|
||
- Commit ID: [commit_hash]
|
||
- Commit Message: [message]
|
||
|
||
## 备注
|
||
[其他需要说明的内容]
|
||
```
|
||
|
||
### 功能更新文档模板
|
||
|
||
```markdown
|
||
# 功能更新: [功能名称]
|
||
|
||
**日期**: YYYY-MM-DD
|
||
**开发者**: [姓名]
|
||
**相关Issue**: #[编号]（如有）
|
||
|
||
## 功能概述
|
||
[简要描述新功能的目的和价值]
|
||
|
||
## 需求背景
|
||
[为什么需要这个功能]
|
||
|
||
## 设计方案
|
||
[技术设计方案描述]
|
||
|
||
### 架构变更
|
||
[如有架构层面的变更，在此说明]
|
||
|
||
### API设计
|
||
[如果是库函数，描述API接口]
|
||
|
||
## 实现细节
|
||
|
||
### 新增文件
|
||
- `src/xxx.cpp` - [文件说明]
|
||
- `include/xxx.h` - [文件说明]
|
||
|
||
### 修改文件
|
||
- `src/yyy.cpp` - [修改说明]
|
||
|
||
## 使用方法
|
||
```cpp
|
||
// 示例代码
|
||
```
|
||
|
||
## 测试结果
|
||
[测试场景和结果]
|
||
|
||
## Git Commit
|
||
- Commit ID: [commit_hash]
|
||
- Commit Message: [message]
|
||
|
||
## 后续计划
|
||
[如有待完善的内容]
|
||
|
||
## 备注
|
||
[其他需要说明的内容]
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
1. **及时归档**: 完成修复或更新后立即归档，不要拖延
|
||
2. **详细文档**: 文档要详细清晰，方便他人理解和维护
|
||
3. **代码备份**: 归档时保存相关代码的副本，便于追溯
|
||
4. **版本控制**: 善用git，每次修复/更新都要commit
|
||
5. **交叉引用**: 文档中包含git commit ID，方便关联
|
||
6. **定期整理**: 定期检查归档目录，清理过时内容
|
||
7. **命名一致**: 严格遵循命名规范，保持一致性
|
||
|
||
## 快速参考
|
||
|
||
### 创建Bug修复归档
|
||
```bash
|
||
DATE=$(date +%Y%m%d)
|
||
BUG_NAME="bug_description"
|
||
mkdir -p archives/bug_fixes/${DATE}_${BUG_NAME}/{code,docs,tests}
|
||
mkdir -p docs/fixes/
|
||
# 编辑文档
|
||
vim archives/bug_fixes/${DATE}_${BUG_NAME}/docs/BUG_${BUG_NAME}_${DATE}.md
|
||
# 复制到快速查阅目录
|
||
cp archives/bug_fixes/${DATE}_${BUG_NAME}/docs/BUG_${BUG_NAME}_${DATE}.md docs/fixes/
|
||
```
|
||
|
||
### 创建功能更新归档
|
||
```bash
|
||
DATE=$(date +%Y%m%d)
|
||
FEATURE_NAME="feature_description"
|
||
mkdir -p archives/updates/${DATE}_${FEATURE_NAME}/{code,docs,tests}
|
||
mkdir -p docs/updates/
|
||
# 编辑文档
|
||
vim archives/updates/${DATE}_${FEATURE_NAME}/docs/UPDATE_${FEATURE_NAME}_${DATE}.md
|
||
# 复制到快速查阅目录
|
||
cp archives/updates/${DATE}_${FEATURE_NAME}/docs/UPDATE_${FEATURE_NAME}_${DATE}.md docs/updates/
|
||
```
|
||
|
||
### 查看归档历史
|
||
```bash
|
||
# 查看所有bug修复
|
||
ls -la archives/bug_fixes/
|
||
|
||
# 查看所有功能更新
|
||
ls -la archives/updates/
|
||
|
||
# 查看所有版本
|
||
ls -la archives/versions/
|
||
```
|
||
|
||
## 维护说明
|
||
|
||
本规范文档应该：
|
||
- 随着项目发展持续更新
|
||
- 被所有项目成员遵守
|
||
- 在项目README中引用
|
||
|
||
最后更新: 2025-11-15
|
||
```
|