Kivy 版本演进全解：从 1.0 到 2.3 的 Changelog 结构与自动生成机制

Kivy 版本演进全解：从 1.0 到 2.3 的 Changelog 结构与自动生成机制

【免费下载链接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS项目地址: https://gitcode.com/gh_mirrors/ki/kivy

本文以仓库中的 changelog.rst 为主线，系统梳理 Kivy 自 2011 年 2 月 1.0.0 发布至 2.3.0 的完整版本脉络、各版本条目分类规范，以及 Kivy 团队如何用 changelog_parser.py 从 GitHub Milestone 自动生成 changelog 的机制。读完你可以掌握：升级 Kivy 前如何快速核对 Breaking changes 与 Deprecated 项、changelog 中[:repo:NNNN]标记的解析方式，以及当前仓库版本约束（Python、Cython、Pillow）与 changelog 记录的对应关系。

1. Changelog 文档的组织方式

Kivy 的变更记录统一维护在 doc/sources/changelog.rst，全文约 4795 行，按版本号从新到旧排列。每个大版本标题（如2.3.0）之下，条目按固定的功能域分组。以最新的 2.3.0 为例，其小节依次为：

• Highlights：本版本最重要的能力新增与修复；
• Deprecated：被标记废弃、后续版本可能移除的 API；
• Kv-lang：KV 语言与解析器的变更；
• Misc：杂项（garden 导入、flake8 风格、机器人配置等）；
• Packaging：打包与 CI 镜像变更（如 2.3.0 中新增balenalib/raspberrypi3-debian-python:3.11-bookworm用于树莓派构建）；
• Widgets：kivy.uix层组件变更；
• Core-app / Core-providers / Core-widget：kivy.core、应用层与核心组件的变更；
• Distribution：安装、依赖与 wheel 构建；
• Documentation / Graphics / Tests/ci：文档、图形系统与测试基础设施。

1.1 版本时间线

changelog 中每个版本的标题格式为版本号 (日期)，早期版本都标注了发布日期，完整版本序列如下：

1.2[:repo:NNNN]链接标记的解析

每一条 changelog 条目都带有[:repo:NNNN]形式的前缀，例如 2.3.0 的 Highlights 首条：

- [:repo:`8298`]: core-providers (audio): removes deprecated `status` property

这个repo角色（role）是在 doc/sources/conf.py 中通过 Sphinx 的extlinks配置定义的：它把:repo:映射到 Kivy 仓库的 issues URL 模板（kivy/kivy/issues/{编号}），并在渲染时把编号渲染为#8298这样的 caption。因此每条 changelog 条目都天然可跳转到对应的 PR/Issue，这是该文档可追溯性的关键设计——版本号 + PR 编号共同构成每条变更记录的唯一标识。

2. Changelog 的自动生成机制（源码级剖析）

Kivy 并没有完全手写 changelog。kivy/tools/changelog_parser.py 的模块 docstring 给出了完整的标准流程：

1. 先用gh（GitHub CLI）定义一个viewMilestone别名，通过 GraphQL 查询指定 Milestone 下所有已合并 PR 的编号、标题与标签；
2. 执行gh viewMilestone <milestone号> > prs.json导出 PR 数据；
3. 运行python -m kivy.tools.changelog_parser prs.json changelog.md生成 RST 风格的 changelog 草稿，再人工编辑后粘贴进 doc/sources/changelog.rst。

2.1 依赖 PR 标签（Label）的分组约定

process_changelog函数（changelog_parser.py）的核心逻辑完全建立在一套标签约定之上：

函数会做严格校验：一个 PR 没有Component:标签、或带有多个组件标签时，直接raise ValueError（“One or more PRs have no, or more than one component label”），保证每条变更都有明确归属。

2.2 小节的输出顺序

write_special_section（changelog_parser.py）负责写出每个小节，条目格式固定为- [:repo:{n}]: {title}。输出顺序为：

1. Highlights
2. Deprecated
3. Breaking changes
4. 其余组件小节，按组件名字母序（sorted(grouped.items())）排列，标题取组件名首字母大写（group.capitalize()）

这解释了为什么各版本条目总是“Highlights 打头、Tests/ci 收尾”——它不是人为排版习惯，而是生成器的固定行为。值得注意的是，Highlights/Deprecated/Breaking 与组件小节并非互斥：一条 PR 会同时出现在高亮小节和它所属的组件小节中（例如 2.3.0 的8495同时出现在 Highlights 和 Widgets）。

3. 2.x 系列版本的关键演进

2.x 系列是 Kivy 从 Python 2/3 双支持走向纯 Python 3、并持续强化图形与输入体验的阶段。以下按 changelog 条目逐版本提炼要点。

3.1 2.3.0：清理废弃 API + 抗锯齿图形原语

Highlights（完整继承自 changelog）：

• 8298/8299：core-providers（audio）移除已废弃的status与filename属性；
• 8300：core-providers（window）移除已废弃的toggle_fullscreen方法；
• 8309：新增抗锯齿图形指令SmoothRectangle、SmoothEllipse、SmoothRoundedRectangle、SmoothQuad、SmoothTriangle；
• 8313/8317：Linux 与 macOS 构建脚本为 freetype 编译libpng16，从而支持彩色 emoji 渲染；
• 8315：修复使用 Shift 键选词时向 undo 列表多加了一个位置的问题；
• 8495：粘贴时尊重multiline=True/False，修复backspace与undo后的滚动异常；
• 8497：为虚拟键盘（vkeyboard）新增西班牙语布局 JSON；
• 8503：Pillow 文本 provider 在get_size不可用时回退到get_bbox，兼容新旧 Pillow。

对应源码可以印证：五个Smooth*指令均为cdef class，分别继承RoundedRectangle、Rectangle、Ellipse、Quad、Triangle，见 vertex_instructions.pyx；SmoothLine则定义在 vertex_instructions_line.pxi。

其他值得注意的条目：

• Deprecated：8459废弃kivy.utils.interpolate并改进相关文档；
• Kv-lang：8206改进缩进非法时 KV 解析器的报错信息；
• Misc：8301重构自定义garden导入器，弃用在 Python 3.12 中已移除的imp模块；
• Core-app：8345防止sys.stderr为None（pythonw、PyInstaller 5.7 场景）时应用崩溃；8383修复KIVY_WINDOW=x11下的模板（stencil）操作；
• Core-providers：8296WindowSDL 新增窗口透明度（opacity）特性；8446修复 Windows 缩放非 100% 时Window.mouse_pos不正确的问题；8510为Label新增limit_render_to_text_bbox属性，将文本渲染限制在包围盒内以改善对齐；
• Distribution：8326支持Cython==3.x.x并提升cython_min；8393增加 Python 3.12 支持（测试与 wheel）；8479将 SDL2 升级到 2.28.5、SDL_image 到 2.8.0；8505将 Pillow 限制在>=9.5.0,<11；随后8533/8536/8543依次推进2.3.0rc1→rc2→rc3，体现 Kivy 以rc 轮次收敛稳定版的发布节奏。

3.2 2.2.x：BoxShadow、fit_mode 与构建体系现代化

2.2.0 的 Highlights（摘自 changelog）：

• 7876：Line/SmoothLine修复圆角渲染问题并更新rounded_rectangle参数顺序，同时为rounded_rectangle、rectangle、ellipse、circle增加 getter 方法（该条同时也是 Breaking change）；
• 7882：重写 Bubble 组件；
• 7908：SmoothLine 创建速度提升约 2.5 倍；
• 7942：Windows 下 Config 支持 Unicode；
• 7988：新增KIVY_LOG_MODE环境变量支持；
• 8044：支持 Python 3.11；
• 8056：新增BoxShadow图形指令（阴影效果）；
• 8115：使用 SDL2_ttf 的font_direction与font_script_name；
• 8144：TabbedPanel 新增可鼠标拖拽的 tab 滚动条属性；
• 8162：Label.padding支持上下左右不同取值；
• 8169：Image新增fit_mode特性；
• 8096：引入 SDL 依赖构建脚本与KIVY_DEPS_ROOT。

围绕BoxShadow，Graphics 小节还有后续迭代：8098修复 Adreno GPU 上的 shader 崩溃、8132增加inset内阴影、8138支持水平/垂直独立的spread_radius。仓库中 doc/sources/images/boxshadow_demo.gif 与 boxshadow 系列 SVG 正是该功能的演示素材。

2.2.0 的工程侧变更（Distribution/Tests/ci）：8203将 Linux SDL2 依赖构建从 autotools 迁移到 CMake（对应仓库内 tools/build_linux_dependencies.sh 等脚本）；8223在balenalib/raspberrypi3-*镜像上做 RPi 构建并产出 armv7l wheel；8070移除已在 3.12 被废除的distutils用法；CI 从ubuntu-18.04切换到ubuntu-latest（8084），并全面移除 nosetest 残留配置转向 pytest（8129）。

2.2.1是一个小型 backport 版本：8283将 “Image 组件将 stencil 限制在内部指令” 的修复（原8276）回移过来，外加 CI 超时与文档构建的两处 backport（8288、8252）。

3.3 2.1.0：性能优化与多平台 CI 扩展

• KV：7371允许在 KV 语言中使用 f-strings；
• 性能：7424裸 Widget 创建提速 3 倍，并加速属性 dispatch/设置；7642优化 TextInput 大文本加载时间；
• 特性：7637自定义标题栏（Custom titlebar）支持；7658新增EventManagerBase；7610TextInput 支持滑动滚屏；
• Breaking changes（升级 2.1.0 时需重点核对）：6290Widget 的add/remove/clear_widget签名与基类对齐；7264Camera 的play默认值改为False；7437移除损坏且易混淆的 TextInputsuggestion_text属性；7763移除对已 EOL 的 Python 3.6 的支持；
• 多平台：7663CI 增加 Python 3.10；7678增加 Apple Silicon CI/CD 支持；7769增加 Linux AArch64 wheel 构建支持；6769Kivy 在树莓派 4 上无需 X11 即可运行。

3.4 2.0.0：Python 2 退出历史舞台

2.0.0 是 Kivy 的分水岭版本，changelog 记录的三大 Highlights：

• 6351：移除 Python 2 支持；
• 6368：App 增加 async 支持（异步生命周期，对应仓库内 examples/async/ 目录下的asyncio_basic.py、trio_basic.py等示例）；
• 7084：安装需求中加入基础依赖声明。

其 Breaking changes 列表是升级 2.0 时的核对清单，主要包括：6467Graphics 的filename更名source；6677从 Widget 移除id（id不再作为 Widget 的属性存在）；6918/7021颜色属性全面改用ColorProperty取代ListProperty；6937Base 中将slave更名embedded；6950Cache 以None为键时抛KeyError；6721移除 GPL 许可的 GIF 图像实现。Kv-lang 侧6442让Builder/Factory在 KV 上下文中可直接拷贝使用，6880读取.kv文件默认改用 UTF-8。CI 基础设施方面，6622标志着测试体系从 Travis/AppVeyor 全面切换到 GitHub Actions。

4. 1.x 系列：奠定 Kivy 形态的关键版本

1.x 系列条目在 changelog 中占据约三千余行，以下按版本提炼对后来者影响最大的决策点：

4.1 1.11.0 / 1.11.1（2019 年 6 月）：SDL2 与 Garden 的转折

1.11.0 的 changelog 带有详细的Installation notes，是典型的“发布说明”写法：

• Windows 依赖命名空间迁移（6324）：Windows 依赖包从kivy/deps/xxx下的kivy.deps.xxx命名空间迁移到kivy_deps/xxx下的kivy_deps.xxx命名空间。文档明确给出三种场景的操作建议：不升级 Kivy 则固定旧版kivy.deps.xxx==x.y.z；升级 Kivy 则需手动卸载kivy.deps.xxx（pip 升级时不会替你卸载）再安装kivy_deps.xxx；首次安装按官网说明即可。这一条解释了为什么 Windows 用户升级时依赖冲突频发；
• Linux/macOS wheel（6248）：Linux wheel 可直接pip install kivy，但不含 GStreamer 依赖（无视频/部分音频能力），需另装 ffpyplayer 并设置KIVY_VIDEO=ffpyplayer环境变量；
• 配置系统（6192）：新增KCFG_SECTION_KEY形式的环境变量配置，如KCFG_KIVY_LOG_LEVEL=warning等价于Config.set("kivy", "log_level", "warning")；环境变量优先于config.ini，设置KIVY_NO_ENV_CONFIG=1可整体禁用。该机制在当前源码 kivy/config.py 中仍然可见：仅当KIVY_NO_ENV_CONFIG != '1'时才遍历以KCFG_开头的环境变量并注入配置；
• KV-Python 集成事件（6257）：Widget新增on_kv_post事件（该 Widget 参与的所有 KV 规则应用完成且ids初始化后触发），并新增apply_class_lang_rules方法供继承类覆写，以便在 KV 规则应用前执行代码；
• Garden 迁移：Kivy garden 组件从kivy.garden.flower（存于~/.kivy/garden）迁移到标准 Python 包kivy_garden.flower，从此可被 pip 安装、支持 Cython 化的 flower，且不再依赖私有 garden 工具；
• 废弃与移除（6313）：Pygame 被正式废弃，官方鼓励迁移到 SDL2 及其他 provider；同时5968移除了 ListView 及其全部关联模块，统一由 RecycleView 承担；5990/6169测试框架从 nose 切换到 pytest；
• 实时窗口缩放（6186）：使用 SDL2 窗口后端的桌面平台支持 live resizing；
• 支持渠道（5947）：官方支持从 IRC 迁移到 Discord（提供 matrix 集成）。

1.11.1 则是对 1.11.0 引入的文档、CI 与依赖问题的修复版（6357）。

4.2 更早的版本

• 1.10.0（2017-05-07）：条目覆盖 Core（Camera 增加 opencv4 支持、5962Pango + fontconfig/freetype2 文本 provider）、Graphics（5952CGL 后端优先动态 GL 符号加载）、Packaging（5866树莓派交叉编译支持、5826停止支持 py3.3）等；
• 1.9.x（2015–2016）：Kivy 引入 Python 3 支持的主线版本；
• 1.8.0（2014-01-30）至 1.0.0（2011-02-01）：记录了 Kivy 从初版到稳定框架的完整打磨过程，包括 SDL 2.0 适配、iOS/Android 支持完善、PyInstaller 打包修复等。这些早期条目的行式分组（Core/CI/Graphics/Packaging/Widgets）与 2.x 的Component:标签分组一脉相承。

5. 当前仓库状态与 changelog 的对照

将 changelog 与仓库当前实际文件对照，可以确认版本演进并未断裂：

• 版本元数据：kivy/_version.py 中MAJOR=3, MINOR=0, MICRO=0, RELEASE=False，即当前 master 处于3.0.0.dev0开发周期。该文件被kivy/__init__.py导入并由setup.pyexec（文件头注释说明），非正式发布会追加.dev0后缀——这与 changelog 中8253（"Update version to 2.3.0.dev0 for development"）记录的版本推进方式完全一致；
• Python 版本约束：changelog 2.3.0 记录8393新增 Python 3.12 支持，而当前 pyproject.toml 已要求requires-python = ">=3.11"，classifiers 覆盖 3.11–3.14，[tool.kivy]段声明python_versions = "3.11 - 3.14"，说明 master 已推进到更高版本基线；
• Cython 约束：changelog8326（支持 Cython 3.x）在 pyproject.toml 中落地为cython_min = "0.29.1"、cython_max = "3.2.0"；
• Pillow 约束：changelog8505在 2.3.0 中将 Pillow 限制为>=9.5.0,<11，当前 master 的可选依赖base = ["pillow>=9.5.0,<12"]、full组为pillow>=12.3,<13，可见依赖区间随新版本持续放宽；
• Changelog 本身的时效：doc/sources/changelog.rst 的最新条目停留在 2.3.0（rc3 之后），而_version.py已是 3.0.0.dev0——从源码结构看，3.0.0 的 changelog 小节将在其发布流程中由 changelog_parser 生成并追加，这是 Kivy 发布节奏的正常状态，而非文档缺失。

6. 实战建议：如何把 changelog 用作升级核对单

1. 先读目标版本的 “Breaking changes” 与 “Deprecated”：例如升级到 2.0.0 需检查代码是否依赖Widget.id、filename（图形指令）、ListProperty颜色属性；升级到 2.3.0 需确认没有使用 audio 的status/filename属性或Window.toggle_fullscreen()；
2. 用 PR 编号回溯细节：每条[:repo:NNNN]都可定位到原始 PR 讨论，遇到“行为变化类”条目（如7876的rounded_rectangle参数顺序调整）务必结合 PR 说明核对调用点；
3. 关注 Distribution 小节的依赖变化：SDL、Pillow、Cython 的版本区间变更直接影响 pip 安装与 wheel 可用性（如 2.3.0 的8479将 SDL2 提升到 2.28.5）；
4. 注意平台相关的安装提示：如 1.11.0 针对 Windowskivy.deps.xxx→kivy_deps.xxx迁移的手动卸载要求，以及 Linux wheel 不含 GStreamer 时通过KIVY_VIDEO=ffpyplayer补齐音视频能力的方式；
5. 配置调试：排查版本间行为差异时，可借助 1.11.0 引入的KCFG_环境变量机制（实现见 kivy/config.py）在不动config.ini的情况下覆盖单条配置，或用KIVY_NO_ENV_CONFIG=1排除环境变量干扰。

7. 小结

doc/sources/changelog.rst 不仅是 Kivy 十余年演进的编年史，其结构本身也是一套可执行的工程规范：由 PR 标签（Component:/Notes:）驱动、由 changelog_parser.py 分组渲染、由 conf.py 的extlinks保证每条记录可溯源到具体 PR。从 1.11.0 的 SDL2 转向与 Pygame 废弃，到 2.0.0 的 Python 2 退出，再到 2.3.0 的抗锯齿图形原语与 Python 3.12 支持，changelog 中每个条目的分类、高亮与废弃标记都对应着一次明确的 API 决策——升级 Kivy 时，这份文档就是最可靠的核对清单。

【免费下载链接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS项目地址: https://gitcode.com/gh_mirrors/ki/kivy