Create migration guide for BoxDecoration.shape

src/release/breaking-changes/boxdecoration-shape-migration.md

@@ -0,0 +1,101 @@
+---
+title: Migration guide for BoxDecoration.circle
+description: Removal of BoxDecoration.circle and how to migrate
+---
+
+## Summary
+
+The `shape` parameter of `BoxDecoration` has been deprecated. Existing uses
+of `BoxDecoration(shape: BoxShape.circle)` should use
+`ShapeDecoration(shape: CircleBorder())` instead.
+
+## Context
+
+The enum property `BoxShape shape` from `BoxDecoration` has been deprecated,
+as increasing the number of supported shapes through enums created
+unnecessary complexity and performance costs.
+Users should migrate to use `ShapeDecoration` in conjunction with
+`ShapeBorder`, the replacement for `BoxShape`.
+
+## Description of change
+
+Remove `BoxDecoration(shape: BoxShape.circle)` and `BoxDecoration.shape`.
+
+- Replace `BoxDecoration(shape: BoxShape.circle)` with
+`ShapeDecoration(shape: CircleBorder())`.
+- Remove the `BoxDecoration.shape` property from
+`BoxDecoration(shape: BoxShape.rectangle)`.
+
+## Migration guide
+
+When you use `Border`,
+`CircleBorder(width: ..., color: ..., strokeAlign: ...)` inherits
+the `Border.all(width: ..., color: ..., strokeAlign: ...)` values.
+
+Code before migration:
+
+<!-- skip -->
+```dart
+BoxDecoration(
+  shape: BoxShape.circle,
+)
+
+BoxDecoration(
+  shape: BoxShape.circle,
+  border: Border.all(width: 20, color: Colors.red),
+  boxShadow: [],
+)
+
+BoxDecoration(
+  shape: BoxShape.rectangle,
+)
+```
+
+Code after migration:
+
+<!-- skip -->
+```dart
+ShapeDecoration(
+  border: CircleBorder(),
+)
+
+ShapeDecoration(
+  border: CircleBorder(width: 20, color: Colors.red),
+  shadows: [],
+)
+
+BoxDecoration()
+```
+
+## Timeline
+
+Landed in version: TBD<br>
+In stable release: not yet
+
+## References
+
+{% include docs/master-api.md %}
+
+API documentation:
+
+* [`BoxDecoration` stable][]
+* [`BoxDecoration` main][]
+
+Relevant issues:
+
+* [Deprecate `BoxDecoration.shape` issue][]
+
+Relevant PRs:
+
+* [Deprecate `BoxDecoration.shape` PR][]
+
+<!-- Stable channel link: -->
+[`BoxDecoration` stable]: {{site.api}}/flutter/lib/src/painting/BoxDecoration-class.html
+
+<!-- Master channel link: -->
+{% include docs/master-api.md %}
+
+[`BoxDecoration` main]: {{site.master-api}}/flutter/lib/src/painting/BoxDecoration-class.html
+
+[Deprecate `BoxDecoration.shape` issue]: {{site.repo.flutter}}/issues/108051
+[Deprecate `BoxDecoration.shape` PR]: {{site.repo.flutter}}/pull/108052

src/release/breaking-changes/index.md

@@ -28,6 +28,7 @@ release, and listed in alphabetical order:
 [Deprecated API removed after v3.3]: {{site.url}}/release/breaking-changes/3-3-deprecations
 [ThemeData's toggleableActiveColor property has been deprecated]: {{site.url}}/release/breaking-changes/toggleable-active-color
 [iOS FlutterViewController splashScreenView made nullable]: {{site.url}}/release/breaking-changes/ios-flutterviewcontroller-splashscreenview-nullable
+[Deprecate BoxDecoration.shape]: {{site.url}}/release/breaking-changes/boxdecoration-shape-migration.md
 
 ### Released in Flutter 3.3