Maintainer Guide¶
这篇文档是为维护者准备的, 提供了关于如何管理和维护该项目的指南.
Project Background¶
为了理解整个项目架构, 我们首先需要了解这个项目的背景和设计初衷.
The Ultimate Python Project Development Workflow 博文详细介绍了我的 Python Project Development Workflow 在十多年间的进化历程. 而 pywf_open_source 正是该博文中提到的 open_source workflow 的具体实现, 专门为发布在 PyPI 上的开源项目量身设计.
接下来让我们了解这个项目的完整架构组成.
Repository Architecture¶
虽然 pywf_open_source 是 open_source workflow 自动化逻辑的核心实现, 但完整的解决方案实际上由三个相互关联的 GitHub Repository 组成:
pywf_open_source-project: Automation Library, 实现了核心的自动化逻辑
cookiecutter_pywf_open_source_demo-project: Seed Repository, 作为具体项目示例, 展示了使用
open_sourceworkflow 的开源项目的标准目录结构和代码实现cookiecutter-pywf_open_source: Cookiecutter Template, 基于种子项目创建的参数化模板, 能够一键生成符合
pywf_open_sourceworkflow 规范的新项目
这三个 Repository 的协作关系为我们的开发工作流程奠定了基础.
Development Workflow¶
在实际开发过程中, 我们需要同时维护和迭代两个核心模块:
自动化逻辑: 在 pywf_open_source-project Repository 中实现和完善
种子项目: 在 cookiecutter_pywf_open_source_demo-project Repository 中维护和更新
开发过程中, 这两个 Repository 需要保持同步迭代. 当两个 Repository 都达到稳定状态后, 我们再运行 cookiecutter-pywf_open_source 中的自动化脚本, 将种子项目打包成可重用的模板.
Note
值得注意的是, pywf_open_source-project 本身就是一个开源项目, 它采用自身的 pywf_open_source workflow 进行管理和维护 (这在软件工程中被称为自举 bootstrapping).
为了确保代码质量, 我们采用了完善的测试策略.
Testing Strategy¶
本项目采用测试驱动的开发方式, 通过在测试用例中完整验证所有 workflow 功能来确保代码质量. 由于项目的核心价值在于为其他项目提供开发流程加速, 我们需要通过 cookiecutter_pywf_open_source_demo-project 种子项目来验证自动化功能的有效性.
因此, 你会在项目根目录下看到完整的种子项目代码: pywf_open_source-project/cookiecutter_pywf_open_source_demo-project.
核心测试文件 tests/test_pywf.py 完整模拟了 Python 项目开发的全生命周期, 包括:
创建和删除虚拟环境
依赖管理 (支持全量安装和分组安装)
多种测试类型 (unit test, coverage test, integration test, load test)
本地文档构建和预览
项目打包和本地预览
PyPI 发布流程
GitHub Release 创建
自动配置 https://codecov.io 代码覆盖率追踪
自动配置 https://readthedocs.org 文档构建
GitHub Repository 元数据自动更新
测试完成后, 我们需要保持种子项目的同步更新.
Seed Project Sync¶
在种子项目的维护过程中, 有一个重要的原则需要严格遵守: 所有对 cookiecutter_pywf_open_source_demo-project 种子项目的修改都必须在 Source Repository cookiecutter_pywf_open_source_demo-project 中进行, 因为这里是 Source of Truth.
修改完成后, 需要运行 sync_cookiecutter_pywf_open_source_demo.py 脚本, 将最新代码同步到测试环境 pywf_open_source-project/cookiecutter_pywf_open_source_demo-project 进行验证.
同步完成后, 我们需要对自动化库进行全面测试.
Automation Library Testing¶
随着自动化脚本和种子项目的不断完善, 我们需要频繁地运行 tests/test_pywf.py 来确保核心功能的稳定性. 测试代码包含许多实际场景的考虑:
某些功能依赖 home_secret.json 中的认证信息, 在 CI 环境中不便测试
部分功能在 Windows 系统中可能不够稳定
涉及改变 SaaS 服务状态的功能在 CI 中需要跳过执行
当 Code Coverage Test 覆盖了所有本地可运行, 无副作用的功能后, 我们就可以认为 Automation Library 达到了稳定状态.
接下来需要在真实环境中验证种子项目的可用性.
Real Seed Repository Environment Testing¶
在自动化库测试完成后, 我们需要将 pywf_open_source 安装到全局 Python 环境中, 然后使用种子项目进行真实场景测试. 选择全局安装的原因是这个库类似于 poetry, uv 等 Python 环境管理工具, 推荐采用 “一次安装, 到处运行” 的使用模式.
从 Makefile 中可以看到, 大部分自动化命令都使用全局的 ~/.pyenv/shims/python 来执行.
在 cookiecutter_pywf_open_source_demo-project 种子项目中, 我们需要按照标准流程依次执行所有 make 命令, 全面验证各项功能. 由于这是测试专用的种子项目, 可以放心地进行版本升级, 避免与 PyPI 和 GitHub Release 中的版本产生冲突.
真实环境测试通过后, 我们就可以进行最终的模板发布.