版本控制与工程协作¶
版本控制的目的不是“把文件传到云端”，而是记录设计决策、隔离实验、定位回归，并让另一位学习者能够审阅你的结果。以下流程适用于代码、网表、HDL、脚本、报告和大多数文本化工程文件。
目的与学习成果¶
完成本指南后，你应能：
- 从一个空目录建立可解释的提交历史；
- 用分支隔离风险实验，用标签冻结可复现里程碑；
- 识别不应进入仓库的密钥、原始个人数据和大型生成物；
- 从任意已标记里程碑重建并验证项目；
- 用问题记录和评审说明保存设计取舍。
最小环境¶
- 一个本地版本控制客户端；Git 是常见的开源例子；
- 一个纯文本编辑器和终端；
- 一个只含低风险示例数据的小型 EE 项目；
- 可选的远程托管；离线本地仓库足以完成核心练习。
先记录客户端版本和操作系统。不要把登录令牌写入命令、截图或仓库；远程认证应使用系统凭据存储或平台支持的安全方式。
学习顺序¶
- 建立基线：初始化仓库，写明目标、构建命令、输入和预期输出。
- 练习原子提交：一次提交只表达一个可验证改变，例如“加入 RC 扫频脚本”和“补充单位测试”分开提交。
- 练习差异审阅：提交前逐行检查暂存差异，确认没有生成物、密钥或无关格式变化。
- 隔离实验：在短生命周期分支中改变模型或参数；比较结果后再决定合并或丢弃。
- 冻结里程碑：验证通过后创建带说明的标签，并记录复现入口和已知限制。
- 模拟协作：写一个问题记录，提出可验收目标；用合并请求或等价补丁完成一次自我评审。
二进制 EDA 文件也可版本化，但应同时导出可审阅的原理图 PDF、网表、BOM 或规则报告。导出物用于评审，源工程仍是权威。
验证任务：追踪一次滤波器改版¶
建立一个包含计算脚本、仿真输入和简短报告的 RC 滤波器项目：
- 提交基线参数与理论截止频率；
- 在分支中把一个元件值改为原值的两倍，并在改动前写出预测；
- 运行脚本或仿真，保存机器可读结果；
- 在评审说明中比较预测与结果，解释偏差；
- 合并后创建
v0.1-evidence类似的本地标签； - 在新的临时目录从该标签重建，确认输出一致。
验收不是“命令执行成功”，而是标签、提交、报告和生成命令共同指向同一组参数。
常见失败与排查¶
- 历史充满“update”：缩小每次改动，提交消息写“改变什么以及为什么”。
- 差异被生成文件淹没：补充忽略规则，把可再生输出移到构建目录。
- 二进制文件无法评审：增加文本导出和生成说明，必要时用文件锁或串行编辑。
- 合并后结果变化：检查依赖、随机种子、模型文件和环境变量是否进入证据包。
- 大文件拖慢仓库：先判断是否能重建；不能重建时使用受控制品存储并记录校验和。
- 误提交敏感内容：立即停止共享，轮换受影响凭据，再按平台流程清理历史；单纯删除最新文件不够。
可复现证据¶
每个里程碑至少保留：
- 带说明的标签或不可变提交标识；
README中的一条干净重建路径；- 依赖或工具版本记录；
- 原始输入、参数文件和自动验证命令；
- 输出摘要与校验和，而非只保存截图；
- 问题记录或设计日志中的假设、决定和已知限制。
成本、许可与无障碍¶
核心练习可完全离线并使用自由软件完成。使用托管服务前确认私有仓库额度、导出能力、地区可用性和数据保留条款。仓库中的第三方代码、模型和数据必须保留许可证与来源。
评审信息不要只依赖颜色：在差异说明中明确写出新增、删除和风险。为图和波形提供文本结论；提供补丁文件或打包快照，帮助低带宽学习者参与。
安全边界¶
- 不提交密码、令牌、私人密钥、个人身份信息或受限器件资料；
- 不用公开问题记录披露尚未修复的真实系统漏洞；
- 不从不可信分支直接运行构建脚本或硬件烧录命令；
- 涉及硬件的分支合并后仍须重新执行限流、引脚和额定值检查；
- 历史重写会改变协作基线，只在明确协调并有备份时执行。
完成清单¶
- 仓库能从空目录按说明重建。
- 至少有一次原子提交、一次分支实验和一个带说明标签。
- 忽略规则覆盖密钥、本地缓存和可再生大型输出。
- 每个二进制工程都有可审阅的文本或 PDF 导出。
- 验证命令能给出明确通过或失败。
- 里程碑记录了工具、输入、输出、假设和限制。
- 已完成一次敏感信息与第三方许可检查。