Adding a page on dependency management.#13579
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation's side navigation menu in sites/docs/src/data/sidenav/default.yml by adding a new entry for 'Package dependency management' under the packages and plugins section. There are no review comments, and I have no feedback to provide.
|
Staged preview of the updated docs.flutter.dev site (updated for commit aa0106f): https://flutter-docs-prod--docs-pr13579-versioning-ej79wt5n.web.app |
|
Staged preview of the updated flutter.dev site (updated for commit aa0106f): https://flutter-dev-230821--www-pr13579-versioning-c9m17dzv.web.app |
|
|
||
| :::note Use version ranges, not exact versions | ||
| Some developers specify exact versions in `pubspec.yaml` | ||
| (for example, `foo: 1.0.0`) to guarantee that their builds are predictable. |
There was a problem hiding this comment.
I think we should avoid leading with describing the antipattern; if someone is skimming they might not realize this is us saying what not to do.
How about making the whole box just: "Since pubspec.lock always pins exact versions for predictable builds, you should use ranges in your pubspec.yaml. This allows the [....]"
| (for example, `foo: 1.0.0`) to guarantee that their builds are predictable. | ||
| However, `pubspec.lock` already pins exact versions for predictable builds. | ||
|
|
||
| Specify version ranges (using caret syntax) in your `pubspec.yaml` file |
There was a problem hiding this comment.
I removed this parenthetical in my proposed text because the page hasn't introduced caret syntax yet.
| url_launcher: '>=5.4.0 <6.0.0' | ||
| ``` | ||
| ### Any version |
There was a problem hiding this comment.
I'm torn on whether or not we should have this section. I don't really want to introduce the idea at all, but I guess people will get bad advice from other sources and this gives us a clear place to say why not to do it.
| ``` | ||
|
|
||
| Avoid using `any` because a future package update might introduce breaking | ||
| changes that break your build. |
There was a problem hiding this comment.
Maybe we make this a warning box?
| 1. `package_a` depends on `foo: ^1.0.0`. | ||
| 1. `package_b` depends on `foo: ^2.0.0`. | ||
|
|
||
| ```mermaid |
There was a problem hiding this comment.
I assume this will turn into a diagram? It's just text on the staged version.
| and package_b ^1.0.0, version solving failed. | ||
| ``` | ||
|
|
||
| To read this error message, trace the conflict from the bottom up: |
There was a problem hiding this comment.
Maybe reword this to make it clear that "bottom" here is referring to the dependency graph, not the console output? Because step 1 is about finding something that's at the start of the example output, not the end.
3 participants
As per @stuartmorgan-g.
New file staged here: https://flutter-docs-prod--docs-pr13579-versioning-ej79wt5n.web.app/packages-and-plugins/dependency-management