BorgBackup项目开发指南

BorgBackup项目开发指南

borg Deduplicating archiver with compression and authenticated encryption. 项目地址: https://gitcode.com/gh_mirrors/bo/borg

项目概述

BorgBackup是一个开源的去重备份工具，采用Python语言开发（性能关键部分使用Cython和C实现）。本文将为开发者提供参与BorgBackup项目开发的完整指南。

开发环境搭建

基础环境配置

1. 创建Python虚拟环境：

   python3 -m venv borg-env
   source borg-env/bin/activate
   

2. 安装开发依赖：

   pip install -r requirements.d/development.txt
   

3. 安装pre-commit钩子：

   pre-commit install
   

文档构建

BorgBackup使用Sphinx生成文档：

pip install -r requirements.d/docs.txt
cd docs/
make html

生成的HTML文档位于docs/_build/html/目录。

代码规范与质量保证

代码格式化

项目采用black进行自动代码格式化：

pip install -r requirements.d/codestyle.txt
black --check .  # 仅检查格式
black .          # 自动格式化代码

测试框架

BorgBackup使用tox管理测试环境：

fakeroot -u tox  # 运行全部测试

测试用例位于borg/testsuite包中，支持多种运行方式：

# 运行特定测试模块
fakeroot -u tox borg.testsuite.locking

# 排除特定测试
fakeroot -u tox borg.testsuite.locking -- -k '"not Timer"'

# 详细输出模式
fakeroot -u tox borg.testsuite -- -v

分支模型与开发流程

分支策略

1. 主分支：master分支用于主要开发
2. 维护分支：x.y-maint格式（如1.4-maint）用于稳定版本维护

贡献流程

1. 从最新主分支创建特性分支：

   git checkout master
   git pull
   git checkout -b feature-name
   

2. 开发完成后提交代码：

   git add .
   git commit -m "描述性提交信息"
   git push -u origin feature-name
   

3. 创建Pull Request到主仓库的对应分支

代码提交规范

• 保持提交原子性（一个提交解决一个问题）
• 功能变更与代码风格修改分开提交
• 提交信息清晰描述变更内容
• 引用相关issue编号（如"Fix #1234"）

高级开发主题

压缩算法扩展

如需添加新的压缩算法，建议先与社区讨论实现方案，确保算法符合项目需求。

独立二进制构建

使用PyInstaller创建独立可执行文件：

pip install pyinstaller
pyinstaller -F -n borg-PLATFORM borg/__main__.py

构建完成后进行签名：

for file in dist/borg-*; do gpg --armor --detach-sign $file; done

发布流程

版本发布检查清单

1. 确认里程碑问题已解决

2. 更新CHANGES.rst文件

3. 生成文档和手册页：

   python scripts/make.py build_usage
   python scripts/make.py build_man
   

4. 创建签名标签：

   git tag -s -m "tagged/signed release X.Y.Z" X.Y.Z
   

5. 构建发布包并签名：

   scripts/sdist-sign X.Y.Z
   

6. 上传到PyPI：

   scripts/upload-pypi X.Y.Z
   

7. 构建并签名各平台二进制包

开发最佳实践

1. 日志记录：

   • 调试信息使用DEBUG级别
   • 用户交互信息直接输出到stderr
   • 使用主题日志控制信息输出量

2. 测试覆盖：

   • 新功能必须包含测试用例
   • 修改现有代码需确保测试通过

3. 文档同步：

   • 命令行参数变更需更新嵌入式文档
   • 重大功能变更需更新用户文档

通过遵循这些指南，开发者可以高效地为BorgBackup项目做出贡献，同时保持代码质量和项目一致性。

borg Deduplicating archiver with compression and authenticated encryption. 项目地址: https://gitcode.com/gh_mirrors/bo/borg