Luigi 发布流程指南：维护者如何将 Luigi 源码发布到 PyPI-开发者社区

Luigi 发布流程指南：维护者如何将 Luigi 源码发布到 PyPI

【免费下载链接】luigiLuigi is a Python module that helps you build complex pipelines of batch jobs. It handles dependency resolution, workflow management, visualization etc. It also comes with Hadoop support built in.项目地址: https://gitcode.com/gh_mirrors/lu/luigi

本篇指南面向拥有 PyPI 推送权限的 Luigi 维护者，完整讲解从版本号更新、源码构建到twine上传、打 Tag 的官方发布流程，并结合仓库源码（luigi/__meta__.py、setup.py）剖析版本号的唯一来源与打包机制。读完本文，你将能够独立完成一次 Luigi 的正式版本发布，并理解 Luigi 当前的版本策略（非固定节奏、近似语义化版本）。

适用对象与前置条件

本文描述的发布流程仅适用于Luigi 的维护者（maintainers），即同时具备以下两种权限的人：

对 Luigi 上游仓库具有 push 权限；
对 PyPI 上的luigi项目具有上传（push access）权限。

普通用户安装 Luigi 无需本文流程，直接pip install luigi即可；本文讨论的是“把新版本交付给所有用户”的发布环节。

在执行发布操作前，需要先确保本机环境满足基本要求：Python 环境可用、setuptools可用（发布脚本基于setup.py），并安装好上传工具twine：

pip install twine

twine是 PyPI 官方推荐的包上传工具，相比直接使用python setup.py upload，它支持更安全的凭证处理与 HTTPS 校验，是发布上传环节的关键依赖。

Luigi 发布流程八步详解

Luigi 的官方发布流程记录在仓库根目录的 RELEASE-PROCESS.rst 中，共八个步骤。下面逐一展开说明。

第 1 步：确认 twine 已安装

pip install twine

第 2 步：更新版本号

版本号唯一定义在 luigi/meta.py 中：

__version__ = '3.6.0'

当前仓库中的版本号为3.6.0。__meta__.py同时维护了__author__、__contact__、__license__（Apache License 2.0）与__status__（Production）等元信息。发布新版本时，只需将这里的__version__更新为目标版本号，全仓库的版本号只有这一个来源。

第 3 步：提交变更

以简单的提交信息提交版本号变更，官方建议使用类似如下的提交信息：

Version x.y.z

第 4 步：推送到上游仓库

将提交推送到 Luigi 的 GitHub 上游仓库（spotify/luigi 主线），确保发布代码已合入主干。

第 5 步：清理旧的分发产物

执行rm -rf dist清空dist/目录，避免旧版本的 sdist/wheel 产物残留导致误上传。

第 6 步：构建源码分发包（sdist）

python setup.py sdist

该命令会在dist/目录下生成luigi-x.y.z.tar.gz源码分发包。构建过程由 setup.py 驱动。

第 7 步：上传到 PyPI

twine upload dist/*

将dist/下构建出的所有分发文件（如luigi-x.y.z.tar.gz）一并上传至 PyPI。上传时twine会提示输入 PyPI 凭证，或读取本机已配置的凭据。

第 8 步：在 GitHub 上打 Tag 并撰写 changelog

在 GitHub 的 Releases 页面为本次发布添加一个 Tag（如3.6.0），并手写一份 changelog，可以参考以往版本发布说明的风格来组织内容。

版本号单一来源：meta.py 与 setup.py 的联动

发布流程第 2 步强调“只在luigi/__meta__.py更新版本号”，这一点有明确的源码依据。

setup.py 在打包时动态读取__meta__.py：

meta = {} with open("luigi/__meta__.py", "r") as f: exec(f.read(), meta) setup( name='luigi', version=meta['__version__'], description=meta['__doc__'].strip(), author=meta['__author__'], url=meta['__contact__'], license=meta['__license__'], ... )

也就是说，python setup.py sdist构建出的分发包，其version字段直接取自__meta__.py中的__version__，无需在其他地方重复维护版本号。

同时，运行时的版本信息也来自同一处：luigi/init.py 执行from luigi.__meta__ import __version__，并将其纳入包的__all__导出。因此用户可以通过以下方式在 Python 中确认所安装的版本：

import luigi print(luigi.__version__)

这种“单一版本源”设计避免了版本号在多个文件中不同步的经典问题，是发布流程第 2 步只需改一个文件的前提。

setup.py 打包内容的补充说明

python setup.py sdist具体打包了哪些内容，同样由 setup.py 决定：

核心包：luigi、luigi.configuration、luigi.contrib、luigi.contrib.hdfs、luigi.tools；
包内静态数据：get_static_files()会递归收集luigi/static与luigi/templates下的 HTML、JS、CSS、PNG、字体等可视化器资源，并连同py.typed（类型标注标记文件）一起作为package_data打进包中——这正是 Luigi 可视化前端（luigi/static/visualiser）能够随包分发的机制；
依赖声明：install_requires中列出了运行期核心依赖，例如python-dateutil>=2.7.5,<3、tenacity>=8,<9、tornado>=5.0,<7；在 Windows 平台（sys.platform == 'nt'）上还会额外限制python-daemon<2.2.0以规避已知问题；
可选扩展：extras_require提供了jsonschema、prometheus、toml三个 extras，用户可按需安装；
命令行入口：entry_points注册了luigi、luigid、luigi-grep、luigi-deps、luigi-deps-tree等控制台脚本，分别指向 luigi/cmdline.py 与 luigi/tools 下的实现。

理解这些内容有助于发布前自查：改动了哪些模块、新增了哪些依赖或命令行工具，都应在打包前确认setup.py已同步更新。

版本策略：非固定节奏 + 近似语义化版本

发布流程文档明确指出 Luigi 当前的版本策略：

不按固定时间表发布（not released on any particular schedule），发布节奏由维护团队按需决定；
不严格遵循语义化版本（not strictly abiding semantic versioning），但在条件允许时尽量遵循以下规则：
- major 版本：发生不兼容的 API 变更时升级；
- minor 版本：以向后兼容的方式新增功能时升级；
- patch 版本：进行向后兼容的 bug 修复时升级。

以当前仓库的3.6.0为例，即表示功能层面向后兼容的第三个大版本周期的第六次 minor 发布。发布者在决定新版本号时，应依据上述规则判断改动属于破坏性变更、新功能还是纯修复，再选择对应的版本位。

发布前的质量把关（建议补充环节）

虽然 RELEASE-PROCESS.rst 未强制要求，但维护者在发布前通常应先跑通测试矩阵，仓库通过 tox.ini 配置了完整的验证环境：tox的envlist覆盖 Python 3.7～3.12 的多个平台组合（core、contrib、aws、postgres、cdh/hdp等），并设有docs、flake8、visualiser等独立环境。发布前至少可以执行：