Django-Guardian 项目发布流程优化实践

项目背景

Django-Guardian 是一个流行的 Django 权限管理扩展库，为 Django 提供了对象级别的权限控制能力。随着项目的发展，团队决定优化其发布流程，建立更规范的持续部署机制。

发布流程改进方案

分支策略调整

项目将开发分支从 devel 更名为 next，同时新增 main 分支作为稳定发布分支。这种分支策略与许多开源项目的实践一致：

• next 分支用于开发新功能
• main 分支始终保持与最新稳定版本同步

自动化发布流程

团队通过 GitHub Actions 实现了半自动化的发布流程，主要特点包括：

1. 手动触发机制：当前采用手动触发方式（workflow_dispatch），未来可考虑全自动化
2. 版本校验：发布时会检查 setup.cfg/pyproject.toml 中的版本号与输入标签是否匹配
3. 权限控制：仅项目维护者可在 main 分支上执行发布操作
4. 候选版本支持：支持发布候选版本（如 3.0.0rc1）

发布过程细节

发布流程包含以下关键步骤：

1. 使用 uv 工具构建 Python 包
2. 自动生成发布说明（基于 conventional commits）
3. 在 GitHub 上创建版本发布
4. 触发 ReadTheDocs 文档更新

技术实现要点

版本管理

团队采用了严格的版本校验机制，确保发布版本与代码中声明的版本一致。这种设计避免了人为错误导致的版本不一致问题。

权限体系

项目在 PyPI 和 ReadTheDocs 上建立了完善的维护者权限体系：

• 区分了维护者（Maintainer）和所有者（Owner）权限级别
• 确保关键操作需要适当权限级别

文档同步

发布流程自动触发文档更新，确保代码和文档版本始终保持同步，提高了项目的整体质量。

实践成果

团队已成功发布了 3.0.0 候选版本（3.0.0rc1），验证了新发布流程的有效性。这一改进为项目的长期维护奠定了坚实基础，使版本发布更加规范、可靠。

经验总结

通过这次流程优化，Django-Guardian 项目展示了如何通过自动化工具和规范化流程提升开源项目的维护效率。这种模式值得其他 Django 生态项目借鉴，特别是：

1. 清晰的版本控制策略
2. 分阶段的自动化部署
3. 严格的权限管理体系
4. 代码与文档的同步机制

这些实践不仅提高了项目质量，也为贡献者提供了更清晰的工作流程。