docs: add release migration-guide page for breaking changes and deprecations (#6517)

* docs: add 0.85 release migration pages

* docs: add release migration guides

* docs: refine release change guides

* docs: group release guide pages by version

* update PR template

* apply review suggestions

* add previous releases

* fix #6510

* docs: update link to color cookbook in types.py

* docs: add Declarative dialogs to the sidebar

---------

Co-authored-by: Feodor Fitsner <feodor@appveyor.com>

Author: ndonkoHenri

.agents/skills/flet-deprecation/SKILL.md

@@ -166,6 +166,36 @@ For supported patterns, docs should auto-render:
 Do not duplicate with manual deprecation admonitions in docstrings unless there
 is a special case not covered by the extension.
 
+## Release Docs Updates
+
+When adding a user-visible deprecation, also update the release docs in the
+same change. These pages are the canonical upgrade path, not a separate
+`Deprecations` page.
+
+1. Create or update a migration guide under
+   `website/docs/release/breaking-changes/`.
+   - Group closely related deprecations into one page, especially APIs from the
+     same class/control or the same PR. For example, `DragTargetEvent.x`,
+     `DragTargetEvent.y`, and `DragTargetEvent.offset` belong in one
+     coordinate-fields guide.
+   - Use this page shape: title, `:::note` accuracy callout,
+     `Summary`, `Context`, `Migration guide`, `Timeline`, and `References`.
+   - Keep one-off replacements in prose. Use a table only when the page maps
+     many removed/deprecated APIs to replacements.
+   - In `References`, link relevant API docs, relevant GitHub issue/PR links,
+     and release notes entry for that release.
+2. Add the guide to
+   `website/docs/release/breaking-changes/index.md` under the release's
+   `Deprecations` subsection.
+3. Add the guide to `website/sidebars.yml` under:
+   `Stay up to date` -> `Breaking changes and deprecations` -> `vX.Y.Z`.
+   This keeps individual guide pages in the docs sidebar while grouping them by
+   release.
+4. Update `website/docs/release/release-notes.md` so the release links to the
+   combined `Breaking changes and deprecations` section.
+5. Run `cd website && yarn crocodocs:generate` after sidebar
+   edits, then run `cd website && yarn build`.
+
 ## Testing Guidance
 
 Do not add one-off tests for every API that gets deprecated when it uses an

.agents/skills/prepare-flet-release/SKILL.md

@@ -34,6 +34,13 @@ That skill is the source of truth for item wording, scope selection, and what sh
   * If a related issue or PR is missing the `{version}` milestone, update the milestone on GitHub and keep the link in the changelog.
   * When selecting candidates for `packages/flet/CHANGELOG.md`, prefer items with meaningful Flutter-side impact.
   * When selecting candidates for `sdk/python/packages/*/CHANGELOG.md`, prefer published Python-facing changes; do not include extension-internal Flutter implementation work unless it materially changes user-visible Python behavior.
+* If the release includes breaking changes, API removals, or deprecations,
+  update `website/docs/release/release-notes.md` and
+  `website/docs/release/breaking-changes/index.md`.
+  * Use [`flet-deprecation`](../flet-deprecation/SKILL.md) for deprecation
+    guide requirements and sidebar placement.
+  * Group related deprecations into one migration guide page where possible,
+    and add guide pages under the release version in `website/sidebars.yml`.
 * Scan all changelogs for `Unreleased` sections, not only the root ones:
   * `/CHANGELOG.md`
   * `packages/flet/CHANGELOG.md`
@@ -42,9 +49,14 @@ That skill is the source of truth for item wording, scope selection, and what sh
   `rg -n "^##\\s*\\[?Unreleased\\]?|^##\\s*Unreleased" -S CHANGELOG.md packages/flet/CHANGELOG.md sdk/python/packages/*/CHANGELOG.md`
 * If any changelog has an `Unreleased` section, convert that section into the new release section (`## {new_version}`), preserving and re-sorting its items. Do not leave duplicate release content in both `Unreleased` and `{new_version}`.
   This conversion must be done for every matched changelog from the scan above.
-* Sort items in changelogs as following:
+* Sort items in changelogs as follows, omitting empty sections:
   * New features
   * Improvements
+  * Breaking changes
+  * Deprecations
   * Bug fixes
+  * Documentation
   * Other changes (chore, refactor, etc.)
+  Put removals of previously deprecated APIs under `Breaking changes`, and
+  keep newly deprecated-but-still-working APIs under `Deprecations`.
 * Templates are in `sdk/python/templates/` and automatically packaged as zip artifacts with the GitHub Release. No manual branch creation in external repos is needed.

.github/pull_request_template.md

@@ -1,18 +1,18 @@
 ## Description
 
-<!-- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. -->
+<!-- Please include a summary of the change, relevant motivation, and context. -->
 
 <!-- If this PR fixes an open issue, please link to the issue here. Ex: Fixes #4562 -->
 
-## Test Code
+## Test code
 
 ```python
-# Test code for the review of this PR
+# Minimal test/reproduction code for reviewers, if applicable.
 ```
 
 ## Type of change
 
-<!-- Please delete options that are not relevant. -->
+<!-- select only options relevant to your PR -->
 
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
@@ -22,13 +22,14 @@
 ## Checklist
 
 - [ ] I signed the CLA.
-- [ ] My code follows the style guidelines of this project
-- [ ] I have performed a self-review of my own code
-- [ ] If this PR targets a `release/*` branch, I added a new record to the active root `CHANGELOG.md` section
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] My changes generate no new warnings
-- [ ] New and existing tests pass locally with my changes
-- [ ] I have made corresponding changes to the [documentation](https://github.com/flet-dev/website) (if applicable)
+- [ ] I have performed a self-review of my own code.
+- [ ] My code follows the style guidelines of this project.
+- [ ] I have commented my code, particularly in hard-to-understand areas.
+- [ ] My changes generate no new warnings.
+- [ ] New and existing tests pass locally with my changes.
+- [ ] I have made corresponding documentation changes, if applicable.
+- [ ] I have added changelog entries for user-facing changes, if applicable.
+- [ ] I have updated release guide pages and `website/sidebars.yml` for breaking changes, removals, and deprecations, if applicable.
 
 ## Screenshots
 

CHANGELOG.md

@@ -33,11 +33,19 @@
 * Add `issues` property to `CodeEditor` (along with `Issue` and `IssueType` types) for displaying code analysis error markers in the gutter, with analysis performed on the Python side ([#6407](https://github.com/flet-dev/flet/pull/6407)) by @FeodorFitsner.
 * Add `Page.pop_views_until()` to pop multiple views and return a result to the destination view ([#6326](https://github.com/flet-dev/flet/issues/6326), [#6347](https://github.com/flet-dev/flet/pull/6347)) by @brunobrown.
 * Make `NavigationDrawerDestination.label` accept custom controls and add `NavigationDrawerTheme.icon_theme` ([#6379](https://github.com/flet-dev/flet/issues/6379), [#6395](https://github.com/flet-dev/flet/pull/6395)) by @ndonkoHenri.
-* Add `local_position` and `global_position` to `DragTargetEvent`, deprecating `x`, `y`, and `offset` ([#6387](https://github.com/flet-dev/flet/issues/6387), [#6401](https://github.com/flet-dev/flet/pull/6401)) by @ndonkoHenri.
+* Add `local_position` and `global_position` to `DragTargetEvent` for target-relative and global pointer coordinates ([#6387](https://github.com/flet-dev/flet/issues/6387), [#6401](https://github.com/flet-dev/flet/pull/6401)) by @ndonkoHenri.
 * Added PCM16 streaming to `AudioRecorder`, including `on_stream` chunks and direct upload support via `AudioRecorderUploadSettings` ([#5858](https://github.com/flet-dev/flet/issues/5858), [#6423](https://github.com/flet-dev/flet/pull/6423)) by @ndonkoHenri.
 * Add `Page.theme_animation_style` for customizing the duration and curve of the theme cross-fade between `theme` and `dark_theme` (or disabling it with `AnimationStyle.no_animation()`), exposing Flutter's `MaterialApp.themeAnimationStyle` ([#6476](https://github.com/flet-dev/flet/pull/6476)) by @FeodorFitsner.
 
-### Improvements
+### Breaking changes
+
+* Remove deprecated module-level `margin`, `padding`, `border`, and `border_radius` helper functions (`all()`, `symmetric()`, `only()`, `horizontal()`, `vertical()`) in favor of the corresponding `Margin`, `Padding`, `Border`, and `BorderRadius` classmethods ([#6425](https://github.com/flet-dev/flet/pull/6425)) by @ndonkoHenri.
+
+### Deprecations
+
+* Deprecate `DragTargetEvent.x`, `DragTargetEvent.y`, and `DragTargetEvent.offset`; use `local_position` for target-relative coordinates or `global_position` for global coordinates instead. These APIs are scheduled for removal in `0.88.0` ([#6387](https://github.com/flet-dev/flet/issues/6387), [#6401](https://github.com/flet-dev/flet/pull/6401)) by @ndonkoHenri.
+* Deprecate `Video.show_controls`; set `Video.controls` to `None` to hide controls. This API is scheduled for removal in `0.88.0` ([#6463](https://github.com/flet-dev/flet/pull/6463)) by @ndonkoHenri.
+* Deprecate `Video.playlist_add()` and `Video.playlist_remove()`; mutate `Video.playlist` directly with list methods such as `append()` and `pop()`. These APIs are scheduled for removal in `0.88.0` ([#6463](https://github.com/flet-dev/flet/pull/6463)) by @ndonkoHenri.
 
 ### Bug fixes
 
@@ -72,7 +80,6 @@
 ### Other changes
 
 * Add a declarative `ReorderableListView` app example showing add, remove, and reorder flows with stable item identity ([#6374](https://github.com/flet-dev/flet/pull/6374)) by @FeodorFitsner.
-* Remove deprecated module-level `margin`, `padding`, `border`, and `border_radius` helpers (`all()`, `symmetric()`, `only()`, `horizontal()`, `vertical()`) in favor of the corresponding `Margin`, `Padding`, `Border`, and `BorderRadius` classmethods ([#6425](https://github.com/flet-dev/flet/pull/6425)) by @ndonkoHenri.
 * Centralize Linux apt dependencies in `flet.utils.linux_deps` and update CI workflows and publish docs to consume them dynamically ([#6357](https://github.com/flet-dev/flet/issues/6357), [#6383](https://github.com/flet-dev/flet/pull/6383)) by @ndonkoHenri.
 * Bump `serious_python` to `0.9.12` in the `flet build` template ([#6461](https://github.com/flet-dev/flet/pull/6461)) by @FeodorFitsner.
 

packages/flet/CHANGELOG.md

@@ -12,8 +12,6 @@ _No changes in the `flet` Dart package; version bumped for release coordination
 
 * Add `parseControlWidget()` and `parseControlWidgets()` utilities for converting Flet controls in protocol values to Flutter widgets ([#6463](https://github.com/flet-dev/flet/pull/6463)) by @ndonkoHenri.
 
-### Improvements
-
 ### Bug fixes
 
 * Preserve viewport minimum constraints for short scrollable `View`, `Column`, and `Row` content so main-axis alignment still applies ([#6446](https://github.com/flet-dev/flet/issues/6446), [#6450](https://github.com/flet-dev/flet/pull/6450)) by @ndonkoHenri.
@@ -23,8 +21,6 @@ _No changes in the `flet` Dart package; version bumped for release coordination
 * Resolve absolute-path `src` (e.g. `Image(src="/images/foo.svg")`) against `assets_dir` on web so embedded apps mounted at non-root URLs load assets correctly, pass `data:`/`blob:` URIs through unchanged, preserve origin-relative semantics when `assets_dir` is unset, and add a `window.flet.assetsDir` JS-interop bridge so embedding hosts can supply `assets_dir` to the top-level `FletApp` ([#6470](https://github.com/flet-dev/flet/pull/6470)) by @FeodorFitsner.
 * Coerce `double` to `int` in `parseInt` so float values passed into `int`-typed protocol fields (e.g. `Duration(seconds: 2.0)`) decode correctly instead of falling back to the default ([#6478](https://github.com/flet-dev/flet/issues/6478), [#6480](https://github.com/flet-dev/flet/pull/6480)) by @FeodorFitsner.
 
-### Other changes
-
 ## 0.84.0
 
 ### Improvements

sdk/python/packages/flet-video/CHANGELOG.md

@@ -15,7 +15,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Changed
 
-- `Video.playlist` can now be mutated directly for playlist add and remove operations; `playlist_add()` and `playlist_remove()` are deprecated ([#6463](https://github.com/flet-dev/flet/pull/6463)).
+- `Video.playlist` can now be mutated directly for playlist add and remove operations ([#6463](https://github.com/flet-dev/flet/pull/6463)).
+
+### Deprecated
+
+- `Video.playlist_add()` and `Video.playlist_remove()` are deprecated; mutate `Video.playlist` directly with list methods such as `append()` and `pop()` ([#6463](https://github.com/flet-dev/flet/pull/6463)).
 - `Video.show_controls` is deprecated; set `Video.controls` to `None` to hide controls ([#6463](https://github.com/flet-dev/flet/pull/6463)).
 
 ### Fixed

sdk/python/packages/flet/src/flet/controls/types.py

@@ -1307,7 +1307,7 @@ def __post_init__(self) -> None:
 - a material color from the :class:`~flet.Colors` enum,
 - or a Cupertino color from the :class:`~flet.CupertinoColors` enum.
 
-More information [here](https://flet.dev/docs/cookbook/cookbook/cookbook/colors).
+More information [here](https://flet.dev/docs/cookbook/colors).
 """
 
 # Icons

tools/crocodocs/src/crocodocs/partials.py

@@ -151,6 +151,17 @@ def _render_pypi_partial() -> str:
     """Fetch and render the PyPI package index, filtering non-flet packages and converting admonition syntax to MDX format."""
     from .pypi_index import render_pypi_index
 
+    if os.environ.get("FLET_DOCS_FAST"):
+        return "\n".join(
+            [
+                ":::warning",
+                "The PyPI package index is skipped while `FLET_DOCS_FAST` is set.",
+                "Run the full docs build to refresh this list.",
+                ":::",
+                "",
+            ]
+        )
+
     rendered = render_pypi_index(
         base_url="https://pypi.flet.dev/",
         timeout_s=20.0,

tools/crocodocs/src/crocodocs/pypi_index.py

@@ -506,7 +506,10 @@ def render_pypi_index(
             [
                 "!!! warning",
                 f"    Failed to fetch package index from `{base_url}`.",
+                "    ",
+                "    ```text",
                 f"    {message}",
+                "    ```",
                 "",
             ]
         )

website/blog/2022-06-02-introducing-flet.md

@@ -11,6 +11,8 @@ Flet is a framework for building real-time web, desktop and mobile applications
 
 No more complex architecture with JavaScript frontend, REST API backend, database, cache, etc. With Flet you just write a monolith stateful app in Python only and get multi-user, realtime Single-Page Application (SPA) or a mobile app.
 
+{/* truncate */}
+
 To start developing with Flet, you just need your favorite IDE or text editor. No SDKs, no thousands of dependencies, no complex tooling - Flet has built-in web server with assets hosting and desktop clients.
 
 Flet UI is built with [Flutter](https://flutter.dev), so your app looks professional and can be delivered to any platform. Flet simplifies Flutter model by combining smaller "widgets" into ready-to-use "controls" with imperative programming model.