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被标记废弃、后续版本可能移除的 APIKv-langKV 语言与解析器的变更Misc杂项garden 导入、flake8 风格、机器人配置等Packaging打包与 CI 镜像变更如 2.3.0 中新增balenalib/raspberrypi3-debian-python:3.11-bookworm用于树莓派构建Widgetskivy.uix层组件变更Core-app / Core-providers / Core-widgetkivy.core、应用层与核心组件的变更Distribution安装、依赖与 wheel 构建Documentation / Graphics / Tests/ci文档、图形系统与测试基础设施。1.1 版本时间线changelog 中每个版本的标题格式为版本号 (日期)早期版本都标注了发布日期完整版本序列如下版本发布日期changelog 标题标注2.3.0标题无日期由条目 8542 “Happy new year! Updated copyright year to 2024” 推断发布于 2024 年初2.2.1无日期2.2.0 之后的 bugfix 版本2.2.0无日期2.1.0无日期2.0.0无日期1.11.12019-06-201.11.02019-06-011.10.12018-07-081.10.02017-05-071.9.12016-01-011.9.02015-04-031.8.02014-01-301.7.2 / 1.7.1 / 1.7.02013-08-04 / 2013-05-28 / 2013-05-131.6.02013-03-101.5.1 / 1.5.02012-12-13 / 2012-12-091.4.1 / 1.4.02012-09-30 / 2012-09-021.3.02012-06-191.2.02012-04-021.1.1 / 1.1.02012-02-15 / 2012-02-131.0.9 → 1.0.02011-11-14 → 2011-02-01含 1.0.4-beta、1.0.3-alpha、1.0.2-alpha 等预发布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 给出了完整的标准流程先用ghGitHub CLI定义一个viewMilestone别名通过 GraphQL 查询指定 Milestone 下所有已合并 PR 的编号、标题与标签执行gh viewMilestone milestone号 prs.json导出 PR 数据运行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 标签作用Notes: Release-highlight该 PR 同时进入Highlights小节Notes: API-break该 PR 同时进入Breaking changes小节Notes: API-deprecation该 PR 同时进入Deprecated小节Component: 组件名决定该 PR 归入哪个功能域小节如Component: Graphics归入 Graphics函数会做严格校验一个 PR 没有Component:标签、或带有多个组件标签时直接raise ValueError“One or more PRs have no, or more than one component label”保证每条变更都有明确归属。2.2 小节的输出顺序write_special_sectionchangelog_parser.py负责写出每个小节条目格式固定为- [:repo:{n}]: {title}。输出顺序为HighlightsDeprecatedBreaking changes其余组件小节按组件名字母序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完整继承自 changelog8298/8299core-providersaudio移除已废弃的status与filename属性8300core-providerswindow移除已废弃的toggle_fullscreen方法8309新增抗锯齿图形指令SmoothRectangle、SmoothEllipse、SmoothRoundedRectangle、SmoothQuad、SmoothTriangle8313/8317Linux 与 macOS 构建脚本为 freetype 编译libpng16从而支持彩色 emoji 渲染8315修复使用 Shift 键选词时向 undo 列表多加了一个位置的问题8495粘贴时尊重multilineTrue/False修复backspace与undo后的滚动异常8497为虚拟键盘vkeyboard新增西班牙语布局 JSON8503Pillow 文本 provider 在get_size不可用时回退到get_bbox兼容新旧 Pillow。对应源码可以印证五个Smooth*指令均为cdef class分别继承RoundedRectangle、Rectangle、Ellipse、Quad、Triangle见 vertex_instructions.pyxSmoothLine则定义在 vertex_instructions_line.pxi。其他值得注意的条目Deprecated8459废弃kivy.utils.interpolate并改进相关文档Kv-lang8206改进缩进非法时 KV 解析器的报错信息Misc8301重构自定义garden导入器弃用在 Python 3.12 中已移除的imp模块Core-app8345防止sys.stderr为Nonepythonw、PyInstaller 5.7 场景时应用崩溃8383修复KIVY_WINDOWx11下的模板stencil操作Core-providers8296WindowSDL 新增窗口透明度opacity特性8446修复 Windows 缩放非 100% 时Window.mouse_pos不正确的问题8510为Label新增limit_render_to_text_bbox属性将文本渲染限制在包围盒内以改善对齐Distribution8326支持Cython3.x.x并提升cython_min8393增加 Python 3.12 支持测试与 wheel8479将 SDL2 升级到 2.28.5、SDL_image 到 2.8.08505将 Pillow 限制在9.5.0,11随后8533/8536/8543依次推进2.3.0rc1→rc2→rc3体现 Kivy 以rc 轮次收敛稳定版的发布节奏。3.2 2.2.xBoxShadow、fit_mode 与构建体系现代化2.2.0 的 Highlights摘自 changelog7876Line/SmoothLine修复圆角渲染问题并更新rounded_rectangle参数顺序同时为rounded_rectangle、rectangle、ellipse、circle增加 getter 方法该条同时也是 Breaking change7882重写 Bubble 组件7908SmoothLine 创建速度提升约 2.5 倍7942Windows 下 Config 支持 Unicode7988新增KIVY_LOG_MODE环境变量支持8044支持 Python 3.118056新增BoxShadow图形指令阴影效果8115使用 SDL2_ttf 的font_direction与font_script_name8144TabbedPanel 新增可鼠标拖拽的 tab 滚动条属性8162Label.padding支持上下左右不同取值8169Image新增fit_mode特性8096引入 SDL 依赖构建脚本与KIVY_DEPS_ROOT。围绕BoxShadowGraphics 小节还有后续迭代8098修复 Adreno GPU 上的 shader 崩溃、8132增加inset内阴影、8138支持水平/垂直独立的spread_radius。仓库中 doc/sources/images/boxshadow_demo.gif 与 boxshadow 系列 SVG 正是该功能的演示素材。2.2.0 的工程侧变更Distribution/Tests/ci8203将 Linux SDL2 依赖构建从 autotools 迁移到 CMake对应仓库内 tools/build_linux_dependencies.sh 等脚本8223在balenalib/raspberrypi3-*镜像上做 RPi 构建并产出 armv7l wheel8070移除已在 3.12 被废除的distutils用法CI 从ubuntu-18.04切换到ubuntu-latest8084并全面移除 nosetest 残留配置转向 pytest8129。2.2.1是一个小型 backport 版本8283将 “Image 组件将 stencil 限制在内部指令” 的修复原8276回移过来外加 CI 超时与文档构建的两处 backport8288、8252。3.3 2.1.0性能优化与多平台 CI 扩展KV7371允许在 KV 语言中使用 f-strings性能7424裸 Widget 创建提速 3 倍并加速属性 dispatch/设置7642优化 TextInput 大文本加载时间特性7637自定义标题栏Custom titlebar支持7658新增EventManagerBase7610TextInput 支持滑动滚屏Breaking changes升级 2.1.0 时需重点核对6290Widget 的add/remove/clear_widget签名与基类对齐7264Camera 的play默认值改为False7437移除损坏且易混淆的 TextInputsuggestion_text属性7763移除对已 EOL 的 Python 3.6 的支持多平台7663CI 增加 Python 3.107678增加 Apple Silicon CI/CD 支持7769增加 Linux AArch64 wheel 构建支持6769Kivy 在树莓派 4 上无需 X11 即可运行。3.4 2.0.0Python 2 退出历史舞台2.0.0 是 Kivy 的分水岭版本changelog 记录的三大 Highlights6351移除 Python 2 支持6368App 增加 async 支持异步生命周期对应仓库内 examples/async/ 目录下的asyncio_basic.py、trio_basic.py等示例7084安装需求中加入基础依赖声明。其 Breaking changes 列表是升级 2.0 时的核对清单主要包括6467Graphics 的filename更名source6677从 Widget 移除idid不再作为 Widget 的属性存在6918/7021颜色属性全面改用ColorProperty取代ListProperty6937Base 中将slave更名embedded6950Cache 以None为键时抛KeyError6721移除 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.12019 年 6 月SDL2 与 Garden 的转折1.11.0 的 changelog 带有详细的Installation notes是典型的“发布说明”写法Windows 依赖命名空间迁移6324Windows 依赖包从kivy/deps/xxx下的kivy.deps.xxx命名空间迁移到kivy_deps/xxx下的kivy_deps.xxx命名空间。文档明确给出三种场景的操作建议不升级 Kivy 则固定旧版kivy.deps.xxxx.y.z升级 Kivy 则需手动卸载kivy.deps.xxxpip 升级时不会替你卸载再安装kivy_deps.xxx首次安装按官网说明即可。这一条解释了为什么 Windows 用户升级时依赖冲突频发Linux/macOS wheel6248Linux wheel 可直接pip install kivy但不含 GStreamer 依赖无视频/部分音频能力需另装 ffpyplayer 并设置KIVY_VIDEOffpyplayer环境变量配置系统6192新增KCFG_SECTION_KEY形式的环境变量配置如KCFG_KIVY_LOG_LEVELwarning等价于Config.set(kivy, log_level, warning)环境变量优先于config.ini设置KIVY_NO_ENV_CONFIG1可整体禁用。该机制在当前源码 kivy/config.py 中仍然可见仅当KIVY_NO_ENV_CONFIG ! 1时才遍历以KCFG_开头的环境变量并注入配置KV-Python 集成事件6257Widget新增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 工具废弃与移除6313Pygame 被正式废弃官方鼓励迁移到 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.02017-05-07条目覆盖 CoreCamera 增加 opencv4 支持、5962Pango fontconfig/freetype2 文本 provider、Graphics5952CGL 后端优先动态 GL 符号加载、Packaging5866树莓派交叉编译支持、5826停止支持 py3.3等1.9.x2015–2016Kivy 引入 Python 3 支持的主线版本1.8.02014-01-30至 1.0.02011-02-01记录了 Kivy 从初版到稳定框架的完整打磨过程包括 SDL 2.0 适配、iOS/Android 支持完善、PyInstaller 打包修复等。这些早期条目的行式分组Core/CI/Graphics/Packaging/Widgets与 2.x 的Component:标签分组一脉相承。5. 当前仓库状态与 changelog 的对照将 changelog 与仓库当前实际文件对照可以确认版本演进并未断裂版本元数据kivy/_version.py 中MAJOR3, MINOR0, MICRO0, RELEASEFalse即当前 master 处于3.0.0.dev0开发周期。该文件被kivy/__init__.py导入并由setup.pyexec文件头注释说明非正式发布会追加.dev0后缀——这与 changelog 中8253Update version to 2.3.0.dev0 for development记录的版本推进方式完全一致Python 版本约束changelog 2.3.0 记录8393新增 Python 3.12 支持而当前 pyproject.toml 已要求requires-python 3.11classifiers 覆盖 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.0Pillow 约束changelog8505在 2.3.0 中将 Pillow 限制为9.5.0,11当前 master 的可选依赖base [pillow9.5.0,12]、full组为pillow12.3,13可见依赖区间随新版本持续放宽Changelog 本身的时效doc/sources/changelog.rst 的最新条目停留在 2.3.0rc3 之后而_version.py已是 3.0.0.dev0——从源码结构看3.0.0 的 changelog 小节将在其发布流程中由 changelog_parser 生成并追加这是 Kivy 发布节奏的正常状态而非文档缺失。6. 实战建议如何把 changelog 用作升级核对单先读目标版本的 “Breaking changes” 与 “Deprecated”例如升级到 2.0.0 需检查代码是否依赖Widget.id、filename图形指令、ListProperty颜色属性升级到 2.3.0 需确认没有使用 audio 的status/filename属性或Window.toggle_fullscreen()用 PR 编号回溯细节每条[:repo:NNNN]都可定位到原始 PR 讨论遇到“行为变化类”条目如7876的rounded_rectangle参数顺序调整务必结合 PR 说明核对调用点关注 Distribution 小节的依赖变化SDL、Pillow、Cython 的版本区间变更直接影响 pip 安装与 wheel 可用性如 2.3.0 的8479将 SDL2 提升到 2.28.5注意平台相关的安装提示如 1.11.0 针对 Windowskivy.deps.xxx→kivy_deps.xxx迁移的手动卸载要求以及 Linux wheel 不含 GStreamer 时通过KIVY_VIDEOffpyplayer补齐音视频能力的方式配置调试排查版本间行为差异时可借助 1.11.0 引入的KCFG_环境变量机制实现见 kivy/config.py在不动config.ini的情况下覆盖单条配置或用KIVY_NO_ENV_CONFIG1排除环境变量干扰。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考