Flet 发布准备全流程指南版本号、变更日志与弃用审计【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet本文基于 Flet 仓库中维护者使用的prepare-flet-release技能.agents/skills/prepare-flet-release/SKILL.md系统讲解 Flet 一次完整版本发布前需要执行的准备工作如何确定下一个版本号、如何同步版本与创建发布分支、如何从 git 历史提炼变更日志、如何处理Unreleased区块、如何审计弃用deprecation与移除 API以及如何同步发布文档。读完本文你将掌握 Flet 仓库从代码合入 main到生成 GitHub Release之间全部工程化环节的标准操作流程。发布准备的输入与触发时机发布准备工作有两个前置输入上一个 Flet 版本号从仓库的 git tag 中获取本次发布是 minor 还是 major 版本由发布者根据该迭代的变更范围决定。当被要求准备新版本发布时工作内容可归纳为三大块确定版本号并同步代码、撰写变更日志、审计弃用与破坏性变更并同步文档。其中后两块有专门的技能文件支撑发布准备流程会强制引用它们flet-deprecation用于审计目标版本的弃用与 API 移除write-changelog-entry用于起草或打磨每一条变更日志条目它是条目措辞、范围选择和单条条目该写什么不该写什么的唯一事实来源。第一步确定下一个版本号版本号采用三段式语义化版本major.minor.patch递增规则为minor 发布递增第三位patch 位。例如上一个版本是0.86.5则下一个版本为0.86.6major 发布递增第二位minor 位patch 位归零。例如上一个版本是0.86.5则下一个版本为0.87.0。从仓库现状看当前 packages/flet/pubspec.yaml 中version: 1.0.0packages/flet/CHANGELOG.md 与 CHANGELOG.md 均以## 1.0.0为最新区块说明仓库正处于一次 major1.0.0发布周期内。这正好与flet-deprecation技能中弃用 API 在 3 个 minor 版本后移除的策略相互印证1.0.0的 breaking changes 区块中移除的DragTargetEvent.x/y/offset、Video.show_controls等 API都是在0.85.0弃用、按策略于1.0.0移除的见 CHANGELOG.md。第二步创建发布分支并同步版本号确定新版本号后按以下顺序操作拉取最新main确保发布基线不落后于主干从main创建新分支命名规则为prepare-release-{new_version}例如prepare-release-0.87.0在 packages/flet/pubspec.yaml 中写入新版本号。该文件是 Flet Dart 包Flutter 客户端的版本声明version字段是 Flutter 包发布的核心元数据在/client目录执行pub get刷新 client/pubspec.lock 中的依赖锁使锁文件与新的包版本保持一致。这里需要特别说明一个仓库事实packages/flet是 Flutter 端包而 Python 端的版本号集中在 sdk/python/packages/flet 等包的pyproject.toml中。虽然准备流程的核心入口是更新 Dart 包版本但发布是跨 Flutter/Python 两侧协同的——这一点从 packages/flet/CHANGELOG.md 中大量 No changes in thefletDart package; version bumped for release coordination with ... on the Python side 条目可以得到佐证当某个发布只有 Python 侧实质变更时Dart 包仍会提升版本号用于发布协调release coordination。第三步从 git 历史撰写变更日志版本号同步完成后进入发布准备的核心环节——变更日志编写。需要更新的文件包括/CHANGELOG.md仓库级、面向应用开发者的总日志packages/flet/CHANGELOG.md面向 Flutter 包消费者与扩展开发者sdk/python/packages/*/CHANGELOG.md各 Python 包的独立日志例如flet-audio、flet-geolocator等扩展包。候选集构建与条目编写从上一个版本以来的 git 提交、PR 和 issue 中构建候选集每一条目都必须使用 write-changelog-entry 技能来撰写。该技能明确规定了目标文件选择优先选择最窄且正确的日志文件不要把什么都塞进根CHANGELOG.md受众区分根日志面向应用开发者条目描述用户可见的结果packages/flet/CHANGELOG.md只记录 Dart/扩展开发者需要知道的 API、解析器、运行时契约变化不能仅仅因为实现动了 Dart 文件就重复根日志条目扩展包视角sdk/python/packages/package/CHANGELOG.md从已发布 Python 用户的视角写除非 Flutter 内部实现实质性地改变了 Python 可见行为否则不写内部实现细节链接与署名issue 链接在前、PR 链接在后末尾用by login.纯文本署名多个作者用逗号分隔。Milestone 核对所有被日志引用的 PR 和 issue都必须在 GitHub 上挂上{version}里程碑。如果发现某个关联 issue/PR 缺失该里程碑需要在 GitHub 上补挂同时保留日志中的链接。这一步保证了发布说明中承诺的内容与issue 跟踪体系一致。不同日志的条目侧重为packages/flet/CHANGELOG.md挑选条目时优先选择对 Flutter 端有实质影响的变更为sdk/python/packages/*/CHANGELOG.md挑选条目时优先选择已发布且对 Python 用户可见的变更扩展内部的 Flutter 实现工作除非实质改变用户可见的 Python 行为否则不收录。第四步弃用与移除 API 审计如果发布包含破坏性变更、API 移除或新增弃用必须通过 flet-deprecation 技能审计目标版本的弃用状态。审计的核心是把delete_version等于本次发布版本的弃用项视为强制审计项而不是参考性输出。弃用的三种声明模式Python 端弃用有三种标准模式全部有运行时与文档两层元数据字段/属性弃用Annotated[..., V.deprecated(...)]其中V来自sdk/python/packages/flet/src/flet/utils/validation.py函数/方法弃用deprecated(...)来自sdk/python/packages/flet/src/flet/utils/deprecated.py类/控件弃用deprecated_class(...)同源。每种模式都必须设置version弃用开始的版本、delete_version计划移除的版本、reason运行时警告用的纯文本和docs_reason文档专用 Markdown可含交叉引用。当存在替代 API 时必须在reason和docs_reason中点名替代 API。文档侧的弃用标注由sdk/python/packages/flet/src/flet/utils/griffe_deprecations.py扩展自动生成Deprecatedadmonition 与deprecated徽标。移除时间线策略默认策略是弃用后 3 个 minor 版本移除例如0.82.0弃用 →0.85.0移除。除非有获批的例外否则都用该策略设定delete_version。发布审计时推荐用如下命令扫描待移除项rg -n delete_version\s*\s*{new_version}|delete_version\s*\s*\x27{new_version}\x27 -S sdk/python/packages命中结果全部视为本次发布必须处理的工作要么现在移除、要么发现先前遗漏的移除、要么纠正错误的弃用时间线。移除时要求代码、文档、变更日志在同一改动中完成全部确认后合并为一个分组提交提交信息格式为release: remove deprecated APIs for {new_version}只要存在未处理的{new_version}移除项发布准备就不能视为完成。破坏性变更的文档同步涉及破坏性变更时需要同步更新website/docs/updates/release-notes.md发布说明需链接到合并的 Breaking changes 章节website/docs/updates/breaking-changes/index.md在对应版本的Deprecations小节下登记迁移指南website/sidebars.yml将迁移指南页挂到Stay up to date→Breaking changes and deprecations→vX.Y.Z下按版本分组。迁移指南页面采用固定结构标题、:::note准确性提示、Summary、Context、Migration guide、Timeline、References。相关的多个弃用尽量合并到同一页面例如DragTargetEvent.x/y/offset三个坐标字段合并为一篇迁移指南参见 website/docs/updates/breaking-changes/v0-85-0/deprecated-drag-target-event-coordinates.md只有映射关系很多时才用表格。编辑完sidebars.yml后需在website目录运行yarn crocodocs:generate与yarn build验证文档构建。第五步扫描并转换所有 Unreleased 区块发布前必须扫描全部变更日志中的Unreleased区块不仅限于根日志。扫描范围包括/CHANGELOG.mdpackages/flet/CHANGELOG.mdsdk/python/packages/*/CHANGELOG.md推荐检查命令rg -n ^##\s*\[?Unreleased\]?|^##\s*Unreleased -S CHANGELOG.md packages/flet/CHANGELOG.md sdk/python/packages/*/CHANGELOG.md对每个命中的日志文件将Unreleased区块整体转换为新版本区块## {new_version}保留并重新排序其中的条目。必须对扫描到的每个文件都执行转换且不得让同一份发布内容同时存在于Unreleased和{new_version}两个区块中避免重复。第六步条目排序规则日志条目必须按下述顺序排序空章节可以省略New features新功能Improvements改进Breaking changes破坏性变更Deprecations弃用Bug fixes缺陷修复Documentation文档Other changes其他chore、refactor 等两个容易混淆的归类原则已弃用 API 的移除归入Breaking changes用户会失去能力新弃用但仍在工作的 API 归入Deprecations能力保留只是标记了退役时间线。这一排序规则与当前仓库的实际格式一致例如 CHANGELOG.md 的1.0.0区块依次是### New features→### Improvements→### Breaking changes→### Deprecations而 packages/flet/CHANGELOG.md 的0.85.3、0.85.0区块则展示了省略空章节的做法。第七步模板打包与发布物模板位于sdk/python/templates/目录目前包含两类 cookiecutter 模板app/新应用模板包含{{cookiecutter.out_dir}}下的src/main.py、src/assets/icon.png、pyproject.toml、tests/test_main.py与README.mdextension/新扩展模板包含 Python 端包、Flutter 端插件src/flutter/、示例应用examples/与文档docs/。这些模板会自动打包为 zip 产物并随 GitHub Release 发布无需在外部仓库手工创建分支——这是流程中最后一步机械化操作发布准备到这里即告完成。自检清单一次完整的发布准备应逐项核对版本号按 minor/major 规则正确递增且已写入packages/flet/pubspec.yaml已从最新main创建prepare-release-{new_version}分支/client下执行过pub getpubspec.lock已刷新根日志、packages/flet日志、各sdk/python/packages/*日志均已更新条目由write-changelog-entry技能把关日志引用的 PR/issue 均挂上{version}里程碑delete_version {new_version}的弃用项已全部审计并处理移除改动合并为单个release: remove deprecated APIs for {new_version}提交破坏性变更已同步至website/docs/updates/release-notes.md与website/docs/updates/breaking-changes/index.md迁移指南已挂入website/sidebars.yml且yarn crocodocs:generate、yarn build通过所有Unreleased区块已扫描并转换为## {new_version}无重复内容条目已按 New features → Improvements → Breaking changes → Deprecations → Bug fixes → Documentation → Other changes 排序通过这套流程Flet 每次发版都能保证版本号、变更日志、弃用时间线和发布文档四者严格对齐——这也正是仓库中 CHANGELOG.md、packages/flet/CHANGELOG.md 与各扩展包日志能够长期保持高质量、可追溯的原因所在。【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考