企业官网建设流程全解析

pip Changelog（更新日志）指南：读懂 NEWS.rst 与 news 片段的工作机制

【免费下载链接】pipThe Python package installer项目地址: https://gitcode.com/gh_mirrors/pi/pip

pip 是 Python 生态中最核心的包安装工具（本仓库即其源码仓库，项目描述为 "The Python package installer"）。本文以仓库中的 docs/html/news.rst 与根目录 NEWS.rst 为骨架，系统讲解 pip 更新日志的组织方式：由 Sphinx 指令pip-news-include自动嵌入的完整发布历史（自 19.0 到 26.2.1 共 4900 行），由 towncrier 维护、位于news/目录下的未发布变更片段，以及它们的分类体系（Features、Bug Fixes、Vendored Libraries 等）。读完本文，你将掌握如何读懂任何 pip 版本的功能演进脉络、如何在提交中编写规范的 news 片段，以及如何从更新日志反查对应源码实现。

更新日志的入口与组装机制

docs/html/news.rst全文极短，是一个典型的"入口 + 指令"型文档：

========= Changelog ========= .. attention:: Major and minor releases of pip also include changes listed within prior beta releases. .. towncrier-draft-entries:: Not yet released .. pip-news-include:: ../../NEWS.rst

它只承担三件事：

1. 标题与提示：用.. attention::提醒读者，pip 的主要（major）和次要（minor）版本发布内容中，也包含此前所有 beta 版本中列出的变更——即更新日志是累积的，查阅某个正式版本时应连同上一个正式版本之后的 beta 条目一起看。
2. 未发布草稿条目：.. towncrier-draft-entries:: Not yet released由 Sphinx 的 towncrier 扩展生成，展示尚未正式发布版本的变更片段（即 news/ 目录下的内容）。
3. 发布历史嵌入：.. pip-news-include:: ../../NEWS.rst是 pip 自定义的 Sphinx 指令，实现位于 docs/pip_sphinxext.py 中的PipNewsInclude类。它读取相对该文档上级目录的 NEWS.rst，并对每个版本标题自动生成稳定的锚点：

def _iter_lines_with_refs(self, lines: Iterable[str]) -> Iterator[str]: """Transform the input lines to add a ref before each section title. Dots in the version is converted into dash, and a ``v`` is prefixed. This makes Sphinx use them as HTML ``id`` verbatim without generating auto numbering (which would make the anchors unstable). """

即版本号26.2.1会被转换为v26-2-1形式的 HTML 锚点，从而保证跨文档引用的稳定性。任何其他文档需要引用某个 pip 版本的更新日志时，均可借助该锚点精确定位。

注意：这条指令中的../../NEWS.rst是文档内部相对路径，在仓库中实际指向根目录的 NEWS.rst。

发布历史的结构：版本、分类与条目

NEWS.rst 是 pip 的官方 Changelog 主体，按"版本倒序"组织——最新版本在最上方。每个版本区块采用一致的骨架：

<版本号> (<发布日期>) =================== <分类标题> ---------- - 变更条目（附 issue 链接）

以当前最新版本 26.2.1（2026-08-04）为例：

26.2.1 (2026-08-04) =================== Bug Fixes --------- - Reallow keyring installed in a (non-activated) virtual environment to be be used via the ``import`` provider method while installing build dependencies. (`#14227 <https://github.com/pypa/pip/issues/14227>`_)

从源码结构看，pip 更新日志沿用了 PEP 8 风格的文档分类惯例，历史上出现过以下几类标题：

需要说明的是，Enhancements类目只在少数版本（如 26.1）中出现，多数版本将其合并进Features或Bug Fixes，这是 pip 更新日志在不同时期分类口径的差异，阅读历史版本时不必惊讶。

条目书写规范

每个条目都有两个硬性要求：

1. 必须描述用户可感知的行为变化，而不是内部实现细节；
2. 必须附带 GitHub issue/PR 编号链接，形如(`#14227 <https://github.com/pypa/pip/issues/14227>`_)，方便读者回溯讨论与实现。

文件开头还有一段面向维护者的说明（NEWS.rst 第 1–10 行）：不要在 NEWS.rst 中直接新增条目，该文件由 towncrier 工具管理；新增变更应写在news/目录下的片段文件中。

news/ 目录：towncrier 片段机制

news/ 目录是未发布变更的暂存区，当前仓库中共有 14 个片段文件，命名遵循 towncrier 约定<issue编号>.<类型>.rst：

13084.bugfix.rst 14160.trivial.rst 14171.bugfix.rst 14177.trivial.rst 14235.feature.rst 14237.bugfix.rst 8573.bugfix.rst 9456.bugfix.rst certifi.vendor.rst distlib.vendor.rst msgpack.vendor.rst packaging.vendor.rst platformdirs.vendor.rst

例如：

• news/14235.feature.rst：Speed up installing a wheel with console scripts by not resolving every ``PATH`` entry.—— 这是编号 14235 的新功能条目；
• news/13084.bugfix.rst：Fix ``pip``'s self version check reporting an outdated version from the environment instead of the running pip when run as a zipapp.—— 修复以 zipapp 方式运行时自检版本误报的缺陷；
• news/9456.bugfix.rst：Keep ``--version`` available only for pip and prevent its use in subcommands.；
• 形如certifi.vendor.rst的片段用于记录 vendor（内嵌）依赖升级，对应的发布分类是Vendored Libraries。

这些片段在发布时由 towncrier 合并进 NEWS.rst，同时片段文件被清空。合并行为由 pyproject.toml 中的[tool.towncrier]配置控制：

[tool.towncrier] # 片段存放目录 directory = "news/" # 片段渲染模板 template = "tools/news/template.rst"

片段模板位于 tools/news/template.rst，它定义了每个版本区块的分类顺序与标题样式。此外，pyproject.toml 还约束了文档构建时使用的 towncrier 相关依赖（towncrier < 24与sphinxcontrib-towncrier >= 0.2.0a0），sphinxcontrib-towncrier正是.. towncrier-draft-entries::指令的提供者。

从更新日志反查源码：以 26.2 的索引缓存刷新为例

更新日志最大的价值在于：每个条目都能在源码中找到对应实现。以 26.2 引入的索引响应缓存刷新机制为例：

Cache simple responses in accordance to theirCache-Controlheader instead of always revalidating on every request. To refresh cached package index responses and ensure newly published packages are found, use--refresh-package <package>.

在 src/pip/_internal/cli/cmdoptions.py 中可以看到对应的选项定义（约第 1027–1032 行）：

def refresh_package() -> Option: ... "--refresh-package", dest="refresh_package", ...

其回调_handle_refresh_package会校验参数个数，refresh_package随后被注册到索引相关选项组（第 1392 行附近）。这印证了 NEWS 中"--refresh-package <package>用于刷新某个包的索引缓存"的用法——该选项正是为配合 26.2 的Cache-Control缓存语义而新增。同一版本的另一个相关条目也与之呼应：

Newly published packages will no longer be immediately visible to pip if the index uses caching. To install a newly published package, use--refresh-package.

这意味着升级到 26.2 后，如果索引启用了缓存，新发布包不会立即可见，需要显式--refresh-package才能强制刷新；这是更新日志中"Deprecations and Removals"类目下的一条重要行为变更，值得所有依赖内部索引或私有源的用户留意。

版本演进的时间线速览（26.x 与 25.x 重点）

从 NEWS.rst 可梳理出近年 pip 的演进主线：

26.2.1 / 26.2（2026-07 ~ 2026-08）

• 支持 Python 3.15（#14208）；
• 新增--only-deps、--no-require-hashes、--no-proxy-env选项；
• 索引响应按Cache-Control缓存，配合--refresh-package使用；
• 约束文件（含PIP_CONSTRAINT）不再影响隔离构建环境，改用--build-constraint/PIP_BUILD_CONSTRAINT；
• 实验性--use-feature=venv-isolation（以标准虚拟环境隔离构建子进程）；
• 修复 CVE-2026-13346（链接文件名 URL 路径双重解码问题）；
• 支持pylock.toml的upload-time字段，--uploaded-prior-to可配合-r pylock.toml。

26.1 / 26.1.1 / 26.1.2（2026-04 ~ 2026-05）

• 放弃 Python 3.9（#13795）；
• 实验性支持从标准化pylock.toml读取需求（-r pylock.toml，PEP 751 方向）；
• --uploaded-prior-to支持天数时长（如P3D）；
• 复杂的依赖冲突场景下解析提速、大依赖树内存占用下降。

26.0 / 26.0.1（2026-01 ~ 2026-02）

• 命令行帮助输出彩色化；
• 支持 PEP 723 内联脚本元数据安装（--requirements-from-script）；
• 新增--all-releases、--only-final、--uploaded-prior-to选项；
• 实验性--use-feature inprocess-build-deps（同进程安装构建依赖，更快且可靠支持--no-clean、--no-cache-dir）；
• 删除 egg 片段中非裸项目名的支持。

25.3（2025-10）

• 移除setup.py develop旧式 editable 支持（要求 setuptools >= 64）；
• 移除--global-option/--build-option，--config-settings成为唯一入口；
• 新增--build-constraint构建约束；
• pip 自身构建改用 flit-core（不影响用户安装行为）。

25.2 / 25.1 / 25.1.1（2025-04 ~ 2025-07）

• 声明支持 Python 3.14；
• 下载断点续传与重试默认开启，--resume-retries控制重试次数；
• 新增--group（PEP 735 Dependency Groups 安装）；
• 新增实验性pip lock命令（PEP 751）；
• 放弃 Python 3.8；Python 3.14+ 不再允许使用pkg_resources元数据后端；
• 支持 PEP 738 Android wheels、iOS wheels（PEP 730，24.3）。

更早的重要里程碑

• 24.x：pip 自身以 GitHub Actions 可信发布 + PEP 740 数字签名；系统证书与 certifi 证书同时用于 HTTPS 校验（--use-deprecated=legacy-certs可回退）；http-v2新磁盘缓存格式（内存占用更低）。
• 23.x：--break-system-packages（PEP 668 EXTERNALLY-MANAGED）；--keyring-provider；per-requirement--config-settings；新增-C短选项。
• 22.x：--dry-run、pip inspect、PEP 691 JSON 索引、truststore 后端、--report安装报告、PEP 723。
• 21.x：Python 2 支持移除（21.0）；新 resolver 默认启用（20.3 起）；PEP 610 editable 检测。
• 20.x：pip cache命令、pip debug命令、新 resolver（2020-resolver）beta 到默认的演进、manylinux2010/2014 支持。

内嵌依赖（Vendored Libraries）的变更记录

pip 将大量第三方库以 vendor 方式内嵌在 src/pip/_vendor/ 下，每次升级都会在更新日志的Vendored Libraries分类中列出。以 26.2 为例：

Vendored Libraries ------------------ - Upgrade certifi to 2026.6.17 - Upgrade distlib to 0.4.2 - Upgrade idna to 3.18 - Upgrade platformdirs to 4.10.0 - Upgrade pygments to 2.20.0 - Upgrade requests to 2.34.2 - Upgrade tomli to 2.4.1 - Upgrade urllib3 to 2.7.0

内嵌依赖的完整清单记录在 src/pip/_vendor/vendor.txt，而各依赖的补丁位于 tools/vendoring/patches/（如certifi.patch、requests.patch、urllib3.patch等）。26.2 还新增了一项流程性变更：在 vendored 库旁附带 CycloneDX SBOM（软件物料清单）文件，仓库中可找到 src/pip/_vendor/bom.cdx.json。结合更新日志与这些文件，可以完整审计 pip 内嵌依赖的来源、版本与修补情况。

如何利用更新日志排查升级影响

升级 pip 前，建议按以下顺序阅读更新日志：

1. 看Deprecations and Removals：确认自己依赖的选项、环境变量或行为是否被移除。典型例子：26.2 起PIP_CONSTRAINT不再影响隔离构建环境；25.3 移除--global-option；26.1 放弃 Python 3.9。
2. 看Features中带experimental或use-feature的条目：这些功能尚未默认启用，若希望提前体验可显式打开，如--use-feature=venv-isolation、--use-feature=inprocess-build-deps。
3. 看Bug Fixes中的安全条目：带 CVE 编号的修复（如 26.2 的 CVE-2026-13346）应优先升级。
4. 看Vendored Libraries：若你所在环境依赖特定 CA 证书或 HTTP 行为，certifi / requests / urllib3 的升级值得关注。
5. 对照测试：仓库 tests/ 下有大量与更新日志条目对应的回归测试（如test_refresh_package.py、test_lock.py、test_utils_pylock.py），需要深入了解某条变更的实现细节时，可据此反查验证逻辑。

总结

pip 的更新日志体系由三层组成：docs/html/news.rst（入口 + 指令）、NEWS.rst（已发布的完整历史，由 towncrier 管理）与news/（未发布片段）。理解这套机制后，你既可以快速追踪 pip 的功能演进（索引缓存刷新、pylock、venv-isolation 等都是近年主线），也能规范地参与贡献——为新变更在news/目录添加符合命名规范的片段，而非直接修改 NEWS.rst。更新日志是通往源码的最佳索引，配合 docs/pip_sphinxext.py 的指令实现、src/pip/_internal/cli/cmdoptions.py 的选项定义与 tests/ 中的回归测试，你可以对任何一条历史变更做到"文档可读、源码可查、测试可验"。

【免费下载链接】pipThe Python package installer项目地址: https://gitcode.com/gh_mirrors/pi/pip