深入理解dura项目的贡献指南与开发规范

深入理解dura项目的贡献指南与开发规范

dura You shouldn't ever lose your work if you're using Git 项目地址: https://gitcode.com/gh_mirrors/du/dura

项目概述

dura是一个基于Rust开发的版本控制辅助工具，它通过监控Git仓库的变化来自动创建快照，为开发者提供额外的安全保障。该项目采用严谨的工程实践，包括完善的测试体系和清晰的代码规范。

开发流程规范

前期沟通机制

在开始任何实质性开发工作前，开发者应当先就变更内容进行充分讨论。这一实践可以避免以下常见问题：

• 重复尝试已经被验证不可行的方案
• 忽视某些技术限制因素
• 与项目整体架构产生冲突

测试要求

项目对测试有着严格要求，主要分为两类：

1. 功能测试：推荐在startup_test.rs中添加新功能的测试用例，该文件具有良好的可读性结构
2. 单元测试：优先考虑在源文件内部实现的单元测试，它们位于#[cfg(test)]模块中

提交前检查

项目提供了pre-commit.sh脚本，执行以下自动化检查：

• 代码格式化验证
• 静态代码分析
• 测试套件执行
• 其他CI流程中的关键检查项

该脚本比完整CI流程执行更快，适合本地开发环境使用。

文档要求

对于任何变更，需要提供：

• 清晰的行为描述文档
• 必要时包含屏幕截图或GIF动画演示
• 对特殊情况的处理说明

代码编写规范

输出处理规范

项目对程序输出有严格区分：

• 标准输出(stdout)：全部通过日志记录器输出，格式为JSON
• 标准错误(stderr)：用于向用户显示普通文本信息（如锁获取失败等提示）

JSON日志输出应使用序列化结构体，以保持向后兼容性。字段命名应当稳定，避免破坏依赖这些日志的外部脚本。

测试体系设计

单元测试最佳实践

单元测试应当：

• 测试私有函数时不依赖外部系统（如文件系统）
• 保持测试隔离性
• 放在源文件内的#[cfg(test)]模块中

通过良好的代码结构设计，可以实现高覆盖率的单元测试。

集成测试设计

集成测试特点：

• 需要使用文件系统等外部资源
• 存放在专门的/tests目录
• 利用tests/util中的工具类简化测试编写

项目中提供了两个核心测试工具：

1. git_repo工具：

   • 在临时目录中创建Git仓库
   • 支持并行测试执行
   • 自动处理测试间的隔离问题

2. dura工具：

   • 在子进程中调用真实的dura可执行文件
   • 通过环境变量实现并行测试
   • 提供守护进程管理功能，便于测试dura serve等长时间运行的服务

工程实践建议

1. 保持向后兼容：特别是日志格式和命令行接口，变更时要考虑现有用户的使用场景。

2. 关注性能影响：由于dura需要持续监控文件变化，代码性能直接影响用户体验。

3. 错误处理：对可能失败的操作（如文件操作、Git命令执行等）要有完善的错误处理和恢复机制。

4. 并发安全：合理使用锁机制，避免竞态条件，特别是在处理共享资源时。

通过遵循这些规范，开发者可以为dura项目贡献高质量的代码，同时保持项目的可维护性和稳定性。

dura You shouldn't ever lose your work if you're using Git 项目地址: https://gitcode.com/gh_mirrors/du/dura