Git 协作

Git 是课题组工程协作的基础工具。硬件项目同样需要 Git，因为 HDL、脚本、约束和文档都是文本文件。

基础配置

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
git config --global core.editor "code --wait"
git config --global init.defaultBranch main

常用别名：

git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.lg "log --oneline --graph --all"

日常流程

git clone <repo-url>
git checkout -b feature/my-task
git status
git add .
git commit -m "feat: 添加 xxx"
git push

提交前先看 git status 和 git diff，确认没有把临时文件、数据文件、密钥或生成物提交进去。

仓库命名

仓库名统一使用全小写英文、数字和短横线，不使用中文、空格、下划线和大小写混排。这个规则适用于算法、硬件、软件、文档和实验工具仓库。

推荐格式：

<方向或项目>-<对象>-<用途>

示例：

类型	推荐仓库名	说明
算法实验	radar-pointnet-demo	雷达点云模型 demo
数据处理	radar-data-tools	数据解析、转换、可视化脚本
FPGA 工程	fpga-uart-controller	UART 控制器 RTL 工程
板级验证	zcu104-adc-capture	ZCU104 ADC 采集验证
上位机软件	lab-device-manager	设备管理或控制软件
文档资料	lab-handbook	实验室手册

不推荐：

RadarDemo
雷达点云实验
fpga_uart_controller
test
new_project

命名原则：

• 名字要能看出用途，不要叫 test、demo、code 这类泛名。
• 如果绑定具体板卡或芯片，放进仓库名，例如 zcu104-adc-capture。
• 如果是个人探索，可以加 sandbox 或 prototype，例如 radar-tracking-prototype。
• 仓库创建后不要频繁改名，避免链接、脚本和文档失效。

新建仓库内容

新仓库至少包含：

README.md
.gitignore
docs/

README.md 至少写清楚：

• 项目目标。
• 当前状态。
• 环境依赖。
• 运行或构建命令。
• 目录结构。
• 负责人或维护者。

Python 工程与 uv

Python 工程推荐使用 uv 管理环境和依赖。新建仓库时优先保留 pyproject.toml 和 uv.lock，不要提交 .venv/。

初始化示例：

uv init radar-data-tools
cd radar-data-tools
uv add numpy scipy matplotlib
uv run python --version

常用命令：

uv sync
uv add package-name
uv remove package-name
uv run python scripts/example.py
uv run pytest

推荐 .gitignore：

.venv/
__pycache__/
*.pyc
.pytest_cache/
.ruff_cache/
dist/
build/

Python 项目建议目录：

radar-data-tools/
├── README.md
├── pyproject.toml
├── uv.lock
├── src/
│   └── radar_data_tools/
├── scripts/
├── tests/
└── docs/

如果只是一次性实验脚本，也建议写清楚 uv run 命令和输入输出数据位置，避免以后自己也复现不了。

分支约定

main
  └── dev
       ├── feature/uart-ctrl
       └── feature/radar-demo

• main 保持稳定。
• 日常开发从 dev 拉功能分支。
• 合并前做 Review。
• 一个 commit 做一件事，描述写清楚。

FPGA 项目 .gitignore

Vivado 示例：

*.jou
*.log
*.str
*.dcp
*.bit
*.bin
*.mcs
.cache/
.hw/
.sim/
.runs/
.gen/
.ip_user_files/

Quartus 示例：

db/
incremental_db/
output_files/
simulation/
*.qws
*.bak
*.rpt

核心原则：提交源文件、脚本、约束和文档；不要提交可重复生成的产物。

Commit Message

推荐格式：

<类型>: <简要描述>

示例：

feat: 添加 AXI-DMA 读通道控制逻辑
fix: 修复 UART 波特率计算溢出问题
docs: 更新引脚约束说明
test: 添加 FIFO 仿真用例