Deprecate containsSemantics (#12891)

_Issues fixed by this PR (if any):_
flutter/flutter#180534
_PRs or commits this PR depends on (if any):_
flutter/flutter#180538

cc @loic-sharma @chunhtai 

## Presubmit checklist

- [X] If you are unwilling, or unable, to sign the CLA, even for a
_tiny_, one-word PR, please file an issue instead of a PR.
- [X] If this PR is not meant to land until a future stable release,
mark it as draft with an explanation.
- [X] This PR follows the [Google Developer Documentation Style
Guidelines](https://developers.google.com/style)—for example, it doesn't
use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first-person
pronouns).
- [X] This PR uses [semantic line
breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks)
  of 80 characters or fewer.

---------

Co-authored-by: chunhtai <47866232+chunhtai@users.noreply.github.com>
Co-authored-by: Loïc Sharma <737941+loic-sharma@users.noreply.github.com>

Author: 3 people

src/content/release/breaking-changes/deprecate-contains-semantics.md

@@ -0,0 +1,87 @@
+---
+title: Deprecate `containsSemantics` in favor of `isSemantics`
+description: >
+  The `containsSemantics` matcher has been deprecated in favor of
+  `isSemantics` and `matchesSemantics` matchers.
+---
+
+{% render "docs/breaking-changes.md" %}
+
+## Summary
+
+The `containsSemantics` partial matcher is deprecated and replaced by
+`isSemantics` to clarify intent and standardize matcher conventions.
+
+## Context
+
+The `contains` prefix for partial matchers, such as `containsSemantics`, has been 
+replaced with `is` to align with naming conventions:
+
+* **Partial matchers** (e.g. `isSemantics`) match only the properties explicitly
+  provided. Any arguments not provided are ignored.
+* **Exact matchers** (e.g. `matchesSemantics`) verify all values. Any arguments 
+  not provided are expected to match the object's default values.
+
+## Migration guide
+
+To automatically migrate your code, run the following command:
+
+```bash
+dart fix --apply
+```
+
+Alternatively, replace `containsSemantics` with `isSemantics` for partial
+matching (most common case), or `matchesSemantics` if you need to assert 
+exact property values (including defaults for omitted arguments).
+
+Code before migration:
+
+```dart
+expect(
+  tester.getSemantics(find.byType(MyWidget)),
+  containsSemantics(
+    label: 'My Widget',
+    isButton: true,
+  ),
+);
+```
+
+Code after migration:
+
+```dart
+expect(
+  tester.getSemantics(find.byType(MyWidget)),
+  isSemantics(
+    label: 'My Widget',
+    isButton: true,
+  ),
+);
+```
+
+## Timeline
+
+Landed in version: 3.40.0-1.0.pre
+In stable release: 3.40
+
+## References
+
+API documentation:
+
+* [`isSemantics`][]
+* [`matchesSemantics`][]
+
+Relevant issues:
+
+* [Issue 180534][]
+* [Issue 107859][]
+
+Relevant PR:
+
+* [PR 180538][]
+
+<!-- Stable channel link: -->
+[`isSemantics`]: {{site.api}}/flutter/flutter_test/isSemantics.html
+[`matchesSemantics`]: {{site.api}}/flutter/flutter_test/matchesSemantics.html
+[Issue 180534]: {{site.repo.flutter}}/issues/180534
+[Issue 107859]: {{site.repo.flutter}}/issues/107859
+[PR 180538]: {{site.repo.flutter}}/pull/180538

src/content/release/breaking-changes/index.md

@@ -40,6 +40,7 @@ They're sorted by release and listed in alphabetical order:
 * [Stop generating `AssetManifest.json`][]
 * [`$FLUTTER_ROOT/version` replaced by `$FLUTTER_ROOT/bin/cache/flutter.version.json`][]
 * [`FontWeight` also controls the weight attribute of variable fonts][]
+* [Deprecate `containsSemantics` in favor of `isSemantics`][]
 * [Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors][]
 * [Migrating Flutter Android app to Android Gradle Plugin 9.0.0][]
 * [Material 3 tokens update][]
@@ -48,6 +49,7 @@ They're sorted by release and listed in alphabetical order:
 [Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json
 [`$FLUTTER_ROOT/version` replaced by `$FLUTTER_ROOT/bin/cache/flutter.version.json`]: /release/breaking-changes/flutter-root-version-file
 [`FontWeight` also controls the weight attribute of variable fonts]: /release/breaking-changes/font-weight-variation
+[Deprecate `containsSemantics` in favor of `isSemantics`]: /release/breaking-changes/deprecate-contains-semantics
 [Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors]: /release/breaking-changes/separated-builder-find-child-index-callback
 [Migrating Flutter Android app to Android Gradle Plugin 9.0.0]: /release/breaking-changes/migrate-to-agp-9
 [Material 3 tokens update]: /release/breaking-changes/material-color-utilities