7.1 KiB
7.1 KiB
文件组织规范
本文档定义了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修复流程
-
创建工作目录
mkdir -p archives/bug_fixes/YYYYMMDD_bug名称/{code,docs,tests} -
在主代码目录进行修复
- 在
src/,include/等目录直接修复bug - 及时提交git commit
- 在
-
归档修复
- 将修复的文件副本保存到
archives/bug_fixes/YYYYMMDD_bug名称/code/ - 创建修复文档保存到
archives/bug_fixes/YYYYMMDD_bug名称/docs/ - 同时在
docs/fixes/创建文档副本供快速查阅
- 将修复的文件副本保存到
-
文档内容应包含
- Bug描述和复现步骤
- 根本原因分析
- 修复方案说明
- 修改的文件列表
- 测试验证结果
- 相关的git commit ID
功能更新流程
-
创建工作目录
mkdir -p archives/updates/YYYYMMDD_功能名称/{code,docs,tests} -
在主代码目录进行开发
- 在
src/,include/等目录添加新功能 - 及时提交git commit
- 在
-
归档更新
- 将新增/修改的文件副本保存到
archives/updates/YYYYMMDD_功能名称/code/ - 创建更新文档保存到
archives/updates/YYYYMMDD_功能名称/docs/ - 同时在
docs/updates/创建文档副本供快速查阅
- 将新增/修改的文件副本保存到
-
文档内容应包含
- 功能需求描述
- 设计方案
- 实现细节
- API文档（如有）
- 使用示例
- 测试结果
- 相关的git commit ID
版本发布流程
-
创建版本目录
mkdir -p archives/versions/vX.Y.Z/backup -
准备发布
- 更新版本号
- 编写
release_notes.md - 汇总本版本所有bug修复和功能更新
-
创建备份
- 可选：将完整代码打包到
archives/versions/vX.Y.Z/backup/ - 创建git tag
- 可选：将完整代码打包到
-
发布说明应包含
- 版本号和发布日期
- 新增功能列表
- Bug修复列表
- 重大变更说明
- 升级指南（如需要）
文档模板
Bug修复文档模板
# 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]
## 备注
[其他需要说明的内容]
功能更新文档模板
# 功能更新: [功能名称]
**日期**: 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/
创建功能更新归档
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/
查看归档历史
# 查看所有bug修复
ls -la archives/bug_fixes/
# 查看所有功能更新
ls -la archives/updates/
# 查看所有版本
ls -la archives/versions/
维护说明
本规范文档应该：
- 随着项目发展持续更新
- 被所有项目成员遵守
- 在项目README中引用
最后更新: 2025-11-15