From fe87fbefc53f0399bd2a46b1d2b34948411da586 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Fri, 24 Jul 2026 13:39:18 -0500 Subject: [PATCH 1/2] Improve formatting consistency of new dependency management page --- .../dependency-management.md | 181 ++++++++++-------- 1 file changed, 98 insertions(+), 83 deletions(-) diff --git a/sites/docs/src/content/packages-and-plugins/dependency-management.md b/sites/docs/src/content/packages-and-plugins/dependency-management.md index 08664ae115..c331734023 100644 --- a/sites/docs/src/content/packages-and-plugins/dependency-management.md +++ b/sites/docs/src/content/packages-and-plugins/dependency-management.md @@ -8,15 +8,15 @@ description: >- When you build a Flutter app, you often use external packages to add functionality. Each package can depend on other packages, creating a tree of dependencies. -Understanding how Dart and Flutter manage these dependencies helps you resolve -version conflicts and keep your app stable. +Understanding how Dart and Flutter manage these dependencies helps you +resolve version conflicts and keep your app stable. ## How dependency resolution works Your Flutter project specifies dependencies in the `pubspec.yaml` file. When you run `flutter pub get`, -the package manager resolves the dependencies and records the exact versions in -the `pubspec.lock` file. +the package manager resolves the dependencies and +records the exact versions in the `pubspec.lock` file. ### Direct and transitive dependencies @@ -28,7 +28,7 @@ A dependency can be direct or transitive: **Transitive dependencies** : The packages that your direct dependencies depend on. - You do not list these packages in your `pubspec.yaml` file, + You don't list these packages in your `pubspec.yaml` file, but your project requires them to compile. ### The pubspec.lock file @@ -42,60 +42,65 @@ but not for package projects. :::note Use version ranges, not exact versions Since `pubspec.lock` always pins exact versions for predictable builds, -you should use ranges in your `pubspec.yaml` file (possibly using -caret syntax described below). -This allows the version solver to find compatible versions of -transitive dependencies, +you should use ranges in your `pubspec.yaml` file +(possibly using caret syntax described below). +This allows the version solver to find +compatible versions of transitive dependencies, and enables you to safely update dependencies using `flutter pub upgrade`. ::: ## The role of the version solver Unlike some package managers, -the Dart package manager (`pub`) allows only a single version of any package in -your app's compilation tree. +the Dart package manager (`pub`) allows only a +single version of any package in your app's compilation tree. This constraint exists for several reasons: -1. **Type safety:** If your app uses two versions of the same package, - you can get type mismatch errors. - For example, if `v1` and `v2` of a package both define a `User` class, - the Dart compiler treats them as two distinct types. - You cannot pass a `v1.User` to a method expecting a `v2.User`. -1. **Binary size:** Including multiple versions of the same package - increases the size of your application. -1. **Global state:** Many packages use global variables or singletons. - Having multiple copies of the package can lead to inconsistent state or - bugs. - -The version solver's job is to look at all version constraints for your direct -and transitive dependencies and find a single concrete version for each package -that satisfies all constraints. +1. **Type safety:** + If your app uses two versions of the same package, + you can get type mismatch errors. + For example, if `v1` and `v2` of a package both define a `User` class, + the Dart compiler treats them as two distinct types. + You can't pass a `v1.User` to a method expecting a `v2.User`. +1. **Binary size:** + Including multiple versions of the same package + increases the size of your application. +1. **Global state:** + Many packages use global variables or singletons. + Having multiple copies of the package can + lead to inconsistent state or bugs. + +The version solver's job is to look at all version constraints for +your direct and transitive dependencies and find a +single concrete version for each package that satisfies all constraints. ## Understand version constraints When you declare a dependency in `pubspec.yaml`, you specify a version constraint. -Dart packages use [Semantic Versioning](https://semver.org) (SemVer). +Dart packages use [Semantic Versioning][] (SemVer). A version number has three parts: `major.minor.patch` (for example, `2.1.4`). -You can define version constraints in your `pubspec.yaml` file using different -syntaxes: +You can define version constraints in your `pubspec.yaml` file +using different syntaxes: + +[Semantic Versioning]: https://semver.org/spec/v2.0.0-rc.1.html ### Caret syntax The caret syntax (`^`) is the most common way to define a version constraint. -It tells the solver to use any version that is compatible with the specified -version. +It tells the solver to use any version that is +compatible with the specified version. * For stable versions (1.0.0 and higher), - the caret allows updates that do not change the major version: - * `^1.2.3` translates to `>=1.2.3 <2.0.0` + the caret allows updates that don't change the major version: + * `^1.2.3` is equivalent to `>=1.2.3 <2.0.0` * For pre-release/pre-1.0.0 versions, any change in the minor or patch version can introduce breaking changes. Therefore, the caret constraint is more restrictive: - * `^0.8.0` translates to `>=0.8.0 <0.9.0` - * `^0.0.3` translates to `>=0.0.3 <0.0.4` + * `^0.8.0` is equivalent to `>=0.8.0 <0.9.0` + * `^0.0.3` is equivalent to `>=0.0.3 <0.0.4` ### Traditional ranges @@ -108,7 +113,7 @@ dependencies: ### Any version -If you do not specify a version constraint or use `any`, +If you don't specify a version constraint or use `any`, the solver can choose any version: ```yaml @@ -117,8 +122,8 @@ dependencies: ``` :::note Avoid using `any` -We don't recommend using `any` because a future package -update might introduce breaking changes that break your build. +We don't recommend using `any` because a future package update might +introduce breaking changes that break your build. ::: ## Understand dependency conflicts @@ -128,13 +133,13 @@ incompatible versions of the same transitive dependency. Consider this example scenario: -1. Your app depends on two direct dependencies: `package_a` and `package_b`. -1. `package_a` depends on `foo: ^1.0.0`. -1. `package_b` depends on `foo: ^2.0.0`. +1. Your app depends on two direct dependencies: `package_a` and `package_b`. +1. `package_a` depends on `foo: ^1.0.0`. +1. `package_b` depends on `foo: ^2.0.0`. ![Version solver conflict](/assets/images/docs/development/packages-and-plugins/version-solver.png) -Because `foo` cannot be both `^1.0.0` (which is `<2.0.0`) and +Because `foo` can't be both `^1.0.0` (which is `<2.0.0`) and `^2.0.0` (which is `>=2.0.0`), the version solver fails. When you run `flutter pub get` or try to build the app, @@ -148,14 +153,16 @@ So, because my_app depends on both package_a ^1.0.0 and package_b ^1.0.0, version solving failed. ``` -To read this error message, trace the conflict from the bottom up -in the dependency graph: +To read this error message, trace the conflict from the +bottom up in the dependency graph: -1. Identify the conflicting package (`foo`). -1. Find which packages require conflicting versions (`package_a` requires `foo - ^1.0.0` and `package_b` requires `foo ^2.0.0`). -1. Check which direct dependencies pull in those conflicting packages - (`my_app` depends on both `package_a ^1.0.0` and `package_b ^1.0.0`). +1. Identify the conflicting package (`foo`). +1. Find which packages require conflicting versions. + For example, `package_a` requires `foo: ^1.0.0` and + `package_b` requires `foo: ^2.0.0`. +1. Check which direct dependencies pull in those conflicting packages. + For example, `my_app` depends on + both `package_a: ^1.0.0` and `package_b: ^1.0.0`. ## Resolve dependency conflicts @@ -165,15 +172,15 @@ You can use the following steps to resolve dependency conflicts. Before making manual changes, check if newer, compatible versions of your dependencies exist. -Run the following command to upgrade your packages to the latest versions -allowed by your `pubspec.yaml` constraints: +Run the following command to upgrade your packages to the +latest versions allowed by your `pubspec.yaml` constraints: ```bash flutter pub upgrade ``` -To see which packages have newer versions available beyond your current -constraints, run: +To see which packages have newer versions available beyond +your current constraints, run: ```bash flutter pub outdated @@ -185,8 +192,8 @@ run `flutter pub get`. ### Use dependency overrides -If no compatible versions exist because one of the packages has not been -updated, you can force the version solver to use a specific version. +If no compatible versions exist because one of the packages hasn't been updated, +you can force the version solver to use a specific version. Add a `dependency_overrides` section to your `pubspec.yaml` file: ```yaml @@ -198,43 +205,51 @@ dependency_overrides: foo: ^2.0.0 ``` -This overrides all constraints for `foo` and forces the version solver to use -`^2.0.0`. +This overrides all constraints for `foo` and +forces the version solver to use `^2.0.0`. -> [!WARNING] -> Use dependency overrides only as a temporary fix. -> Bypassing the version solver can cause compilation errors or runtime crashes -(such as `NoSuchMethodError`) if the packages are not actually compatible. -> Thoroughly test your app after applying an override. +:::warning +Use dependency overrides only as a temporary fix. +If the packages aren't actually compatible, +Bypassing the version solver can cause +compilation errors or runtime crashes (such as `NoSuchMethodError`). +Thoroughly test your app after applying an override. +::: -> [!NOTE] -> Dependency overrides only apply to the root package. -> If you are developing a package to publish to pub.dev, -> do not include `dependency_overrides` in your `pubspec.yaml` file because -> other projects that depend on your package will ignore them. +:::note +Dependency overrides only apply to the root package. +If you're developing a package to publish to pub.dev, +don't include `dependency_overrides` in your `pubspec.yaml` file because +other projects that depend on your package will ignore them. +::: ### Support the ecosystem -If a package is unmaintained or slow to update, you can help resolve the issue: - -1. **File an issue:** Search the package's repository for existing issues or - file a new issue to notify the maintainer. -1. **Submit a pull request:** If you can fix the conflict, fork the package - repository, update the constraints, and submit a pull request. -1. **Use a git or path dependency:** While waiting for the maintainer to merge - your pull request, you can point your `pubspec.yaml` to your fork or a local - copy: - ```yaml - dependencies: - package_a: - git: - url: https://github.com/your-username/package_a.git - ref: update-foo-dependency - ``` +If a package is unmaintained or slow to update, +you can help resolve the issue: + +1. **File an issue:** + Search the package's repository for existing issues or + file a new issue to notify the maintainer. +1. **Submit a pull request:** + If you can fix the conflict, fork the package repository, + update the constraints, and submit a pull request. +1. **Use a git or path dependency:** + While waiting for the maintainer to merge your pull request, + you can point your `pubspec.yaml` to your fork or a local copy: + + ```yaml + dependencies: + package_a: + git: + url: https://github.com/your-username/package_a.git + ref: update-foo-dependency + ``` ## Learn more -For more information on how Dart manages dependencies, see the following resources: +For more information on how Dart manages dependencies, +see the following resources: * [Package versioning][] on dart.dev * [Pub dependencies][] on dart.dev From 03cae877d66a7c94cc96fb021b799fe68d34150b Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Fri, 24 Jul 2026 13:42:18 -0500 Subject: [PATCH 2/2] Fix capitalization mistake Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- .../src/content/packages-and-plugins/dependency-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/docs/src/content/packages-and-plugins/dependency-management.md b/sites/docs/src/content/packages-and-plugins/dependency-management.md index c331734023..0e413951c6 100644 --- a/sites/docs/src/content/packages-and-plugins/dependency-management.md +++ b/sites/docs/src/content/packages-and-plugins/dependency-management.md @@ -211,7 +211,7 @@ forces the version solver to use `^2.0.0`. :::warning Use dependency overrides only as a temporary fix. If the packages aren't actually compatible, -Bypassing the version solver can cause +bypassing the version solver can cause compilation errors or runtime crashes (such as `NoSuchMethodError`). Thoroughly test your app after applying an override. :::