From c8c888cdb04aa540ad19b92a1479ecca6de07880 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Thu, 27 Feb 2025 09:08:25 +0000 Subject: [PATCH 01/12] Document pubspec_overrides.yaml file --- src/content/tools/pub/dependencies.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/src/content/tools/pub/dependencies.md b/src/content/tools/pub/dependencies.md index fea5a532a5..7ca3cc9ab5 100644 --- a/src/content/tools/pub/dependencies.md +++ b/src/content/tools/pub/dependencies.md @@ -432,6 +432,30 @@ As a result, if you publish a package to pub.dev, keep in mind that your package's dependency overrides are ignored by all users of your package. +If you are using a [pub workspace][workspaces], you can place dependency_overrides in all +workspace packages, but a single package can only be overridden once in the +workspace. + +## `pubspec_overrides.yaml` + +If you locally want to change certain aspects of your `pubspec.yaml` but do not +want to have active changes to the actual file, you can place a file called +`pubspec_overrides.yaml` placed next to `pubspec.yaml`. + +Attributes from that file will override those from `pubspec.yaml`. + +The properties that can be overridden are: + +* `dependency_overrides` +* `workspace` +* `resolution` + +This can be useful to avoid accidentally checking temporary overrides in to +version control. Also it can make it easier to generate overrides from a script. + +In a [pub workspace][workspaces], you can have one `pubspec_overrides.yaml` file +in each workspace package. + ## Best practices Be proactive in managing your dependencies. @@ -570,3 +594,4 @@ to differentiate versions. ↩ [`dart pub upgrade`]: /tools/pub/cmd/pub-upgrade [pubsite]: {{site.pub}} [semantic versioning specification]: https://semver.org/spec/v2.0.0-rc.1.html +[workspaces]: /tools/pub/workspaces From 437d2f1d70224d71a4df5b9adfffdfa7f7818707 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Thu, 27 Feb 2025 09:13:20 +0000 Subject: [PATCH 02/12] Add link in package-layout --- src/content/tools/pub/package-layout.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/src/content/tools/pub/package-layout.md b/src/content/tools/pub/package-layout.md index 045c96d324..99c95f7653 100644 --- a/src/content/tools/pub/package-layout.md +++ b/src/content/tools/pub/package-layout.md @@ -25,7 +25,8 @@ might look like: enchilada/ .dart_tool/ * pubspec.yaml - pubspec.lock ** + pubspec_overrides.yaml ** + pubspec.lock *** LICENSE README.md CHANGELOG.md @@ -34,7 +35,7 @@ enchilada/ bin/ enchilada doc/ - api/ *** + api/ **** getting_started.md example/ main.dart @@ -64,12 +65,16 @@ enchilada/ Don't check it into source control. To learn more, see [Project specific caching for tools](#project-specific-caching-for-tools). + +\** The [`pubspec_overrides.yaml`](/tools/pub/dependencies#pubspec-overrides) + file if present will override certain aspects of pubspec.yaml. Usually you + don't want to check it into source control. -\** The `pubspec.lock` file exists after you've run `dart pub get`. +\*** The `pubspec.lock` file exists after you've run `dart pub get`. Leave it out of source control unless your package is an [application package](/tools/pub/glossary#application-package). -\*** The `doc/api` directory exists locally after you've run +\**** The `doc/api` directory exists locally after you've run [`dart doc`](/tools/dart-doc). Don't check the `api` directory into source control. From 5d9b6ee0cfb78a69bed8954f86d1c7a6f1847178 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Thu, 27 Feb 2025 12:05:27 +0000 Subject: [PATCH 03/12] Fix link achor --- src/content/tools/pub/package-layout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tools/pub/package-layout.md b/src/content/tools/pub/package-layout.md index 99c95f7653..db612daff3 100644 --- a/src/content/tools/pub/package-layout.md +++ b/src/content/tools/pub/package-layout.md @@ -66,7 +66,7 @@ enchilada/ To learn more, see [Project specific caching for tools](#project-specific-caching-for-tools). -\** The [`pubspec_overrides.yaml`](/tools/pub/dependencies#pubspec-overrides) +\** The [`pubspec_overrides.yaml`](/tools/pub/dependencies#pubspec_overrides-yaml) file if present will override certain aspects of pubspec.yaml. Usually you don't want to check it into source control. From 49b112abf9f286cf86ccba07126727082bff9a53 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Thu, 27 Feb 2025 13:39:20 +0100 Subject: [PATCH 04/12] Update src/content/tools/pub/dependencies.md Co-authored-by: Jonas Finnemann Jensen --- src/content/tools/pub/dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tools/pub/dependencies.md b/src/content/tools/pub/dependencies.md index 7ca3cc9ab5..3920799f76 100644 --- a/src/content/tools/pub/dependencies.md +++ b/src/content/tools/pub/dependencies.md @@ -432,7 +432,7 @@ As a result, if you publish a package to pub.dev, keep in mind that your package's dependency overrides are ignored by all users of your package. -If you are using a [pub workspace][workspaces], you can place dependency_overrides in all +If you are using a [pub workspace][workspaces], you can place `dependency_overrides` in all workspace packages, but a single package can only be overridden once in the workspace. From dd2c1a4606eec691adf9bf33deb119fedbbb0816 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Thu, 27 Feb 2025 13:39:49 +0100 Subject: [PATCH 05/12] Update src/content/tools/pub/dependencies.md Co-authored-by: Jonas Finnemann Jensen --- src/content/tools/pub/dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tools/pub/dependencies.md b/src/content/tools/pub/dependencies.md index 3920799f76..d0583c739c 100644 --- a/src/content/tools/pub/dependencies.md +++ b/src/content/tools/pub/dependencies.md @@ -438,7 +438,7 @@ workspace. ## `pubspec_overrides.yaml` -If you locally want to change certain aspects of your `pubspec.yaml` but do not +If you want to change certain aspects of your `pubspec.yaml` but do not want to have active changes to the actual file, you can place a file called `pubspec_overrides.yaml` placed next to `pubspec.yaml`. From 65ca9589d7422b16f7fad6eaabd5482e746dbbd8 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Thu, 27 Feb 2025 13:39:55 +0100 Subject: [PATCH 06/12] Update src/content/tools/pub/package-layout.md Co-authored-by: Jonas Finnemann Jensen --- src/content/tools/pub/package-layout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tools/pub/package-layout.md b/src/content/tools/pub/package-layout.md index db612daff3..5b177c57f0 100644 --- a/src/content/tools/pub/package-layout.md +++ b/src/content/tools/pub/package-layout.md @@ -67,7 +67,7 @@ enchilada/ [Project specific caching for tools](#project-specific-caching-for-tools). \** The [`pubspec_overrides.yaml`](/tools/pub/dependencies#pubspec_overrides-yaml) - file if present will override certain aspects of pubspec.yaml. Usually you + file if present will override certain aspects of `pubspec.yaml`. Usually you don't want to check it into source control. \*** The `pubspec.lock` file exists after you've run `dart pub get`. From 04273dcb62c4881fb4a3d905e3d70f3d4466a3a5 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Fri, 28 Feb 2025 09:05:39 +0100 Subject: [PATCH 07/12] Update src/content/tools/pub/dependencies.md Co-authored-by: Parker Lougheed --- src/content/tools/pub/dependencies.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/tools/pub/dependencies.md b/src/content/tools/pub/dependencies.md index d0583c739c..2619652e67 100644 --- a/src/content/tools/pub/dependencies.md +++ b/src/content/tools/pub/dependencies.md @@ -432,9 +432,9 @@ As a result, if you publish a package to pub.dev, keep in mind that your package's dependency overrides are ignored by all users of your package. -If you are using a [pub workspace][workspaces], you can place `dependency_overrides` in all -workspace packages, but a single package can only be overridden once in the -workspace. +If you are using a [pub workspace][workspaces], you can +have `dependency_overrides` in each workspace package, but +a single package can only be overridden once in the workspace. ## `pubspec_overrides.yaml` From 7b8eb8c5d89a1af01a94779eaa7e43f1ff09eae3 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Fri, 28 Feb 2025 09:06:35 +0100 Subject: [PATCH 08/12] Update src/content/tools/pub/dependencies.md Co-authored-by: Parker Lougheed --- src/content/tools/pub/dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tools/pub/dependencies.md b/src/content/tools/pub/dependencies.md index 2619652e67..865b90e7a7 100644 --- a/src/content/tools/pub/dependencies.md +++ b/src/content/tools/pub/dependencies.md @@ -451,7 +451,7 @@ The properties that can be overridden are: * `resolution` This can be useful to avoid accidentally checking temporary overrides in to -version control. Also it can make it easier to generate overrides from a script. +version control. It can also make it easier to generate overrides from a script. In a [pub workspace][workspaces], you can have one `pubspec_overrides.yaml` file in each workspace package. From 47cd552c6c33739b773d435e15bee68475d67c68 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Fri, 28 Feb 2025 13:49:14 +0000 Subject: [PATCH 09/12] Attempt to clarify --- src/content/tools/pub/dependencies.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/tools/pub/dependencies.md b/src/content/tools/pub/dependencies.md index 865b90e7a7..24c81819e7 100644 --- a/src/content/tools/pub/dependencies.md +++ b/src/content/tools/pub/dependencies.md @@ -438,9 +438,9 @@ a single package can only be overridden once in the workspace. ## `pubspec_overrides.yaml` -If you want to change certain aspects of your `pubspec.yaml` but do not -want to have active changes to the actual file, you can place a file called -`pubspec_overrides.yaml` placed next to `pubspec.yaml`. +If you want to change certain aspects of the resolution your +`pubspec.yaml` but do not want to change the actual file, you can place a file +called `pubspec_overrides.yaml` placed next to `pubspec.yaml`. Attributes from that file will override those from `pubspec.yaml`. From b10ef44cf6d27898cd9ad30ff292606a7dae630e Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Fri, 28 Feb 2025 15:42:44 -0600 Subject: [PATCH 10/12] Add missing 'of' --- src/content/tools/pub/dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tools/pub/dependencies.md b/src/content/tools/pub/dependencies.md index 24c81819e7..618ea8c23c 100644 --- a/src/content/tools/pub/dependencies.md +++ b/src/content/tools/pub/dependencies.md @@ -438,7 +438,7 @@ a single package can only be overridden once in the workspace. ## `pubspec_overrides.yaml` -If you want to change certain aspects of the resolution your +If you want to change certain aspects of the resolution of your `pubspec.yaml` but do not want to change the actual file, you can place a file called `pubspec_overrides.yaml` placed next to `pubspec.yaml`. From d428348af24e3d728f4fc24219bc13e71a2f05b7 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Fri, 28 Feb 2025 15:48:38 -0600 Subject: [PATCH 11/12] Minor copy and formatting changes --- src/content/tools/pub/dependencies.md | 22 ++++++++++++---------- src/content/tools/pub/package-layout.md | 12 +++++++----- 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/src/content/tools/pub/dependencies.md b/src/content/tools/pub/dependencies.md index 618ea8c23c..684f19cf2c 100644 --- a/src/content/tools/pub/dependencies.md +++ b/src/content/tools/pub/dependencies.md @@ -432,15 +432,16 @@ As a result, if you publish a package to pub.dev, keep in mind that your package's dependency overrides are ignored by all users of your package. -If you are using a [pub workspace][workspaces], you can -have `dependency_overrides` in each workspace package, but +If you are using a [pub workspace][workspaces], +you can have `dependency_overrides` in each workspace package, but a single package can only be overridden once in the workspace. -## `pubspec_overrides.yaml` +## `pubspec_overrides.yaml` {:#pubspec-overrides} -If you want to change certain aspects of the resolution of your -`pubspec.yaml` but do not want to change the actual file, you can place a file -called `pubspec_overrides.yaml` placed next to `pubspec.yaml`. +If you want to change certain aspects of +the resolution of your `pubspec.yaml` file, but +do not want to change the actual file, you can +place a file named `pubspec_overrides.yaml` next to the `pubspec.yaml`. Attributes from that file will override those from `pubspec.yaml`. @@ -450,11 +451,12 @@ The properties that can be overridden are: * `workspace` * `resolution` -This can be useful to avoid accidentally checking temporary overrides in to -version control. It can also make it easier to generate overrides from a script. +This can be useful to avoid accidentally +checking temporary overrides in to version control. +It can also make it easier to generate overrides from a script. -In a [pub workspace][workspaces], you can have one `pubspec_overrides.yaml` file -in each workspace package. +In a [pub workspace][workspaces], each workspace package +can have a `pubspec_overrides.yaml` file. ## Best practices diff --git a/src/content/tools/pub/package-layout.md b/src/content/tools/pub/package-layout.md index 5b177c57f0..a30eb2537c 100644 --- a/src/content/tools/pub/package-layout.md +++ b/src/content/tools/pub/package-layout.md @@ -59,16 +59,16 @@ enchilada/ index.html main.dart style.css -``` +``` \* The `.dart_tool/` directory exists after you've run `dart pub get`. Don't check it into source control. To learn more, see [Project specific caching for tools](#project-specific-caching-for-tools). - -\** The [`pubspec_overrides.yaml`](/tools/pub/dependencies#pubspec_overrides-yaml) - file if present will override certain aspects of `pubspec.yaml`. Usually you - don't want to check it into source control. + +\** The [`pubspec_overrides.yaml`][] file, + if present, overrides certain aspects of `pubspec.yaml`. + Usually you don't want to check it into source control. \*** The `pubspec.lock` file exists after you've run `dart pub get`. Leave it out of source control unless your package is an @@ -79,6 +79,8 @@ enchilada/ Don't check the `api` directory into source control. +[`pubspec_overrides.yaml`]: /tools/pub/dependencies#pubspec-overrides + ## The pubspec ```plaintext From aa488ea32a938b2bdaae7bcf2122b0904dca1a8b Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Fri, 28 Feb 2025 15:49:46 -0600 Subject: [PATCH 12/12] Add a /to/pubspec-overrides redirect --- firebase.json | 1 + 1 file changed, 1 insertion(+) diff --git a/firebase.json b/firebase.json index 144e97f535..e50240d7ec 100644 --- a/firebase.json +++ b/firebase.json @@ -387,6 +387,7 @@ { "source": "/to/pub-workspaces", "destination": "/tools/pub/workspaces", "type": 301 }, { "source": "/to/publish-from-github", "destination": "/tools/pub/automated-publishing#publishing-packages-using-github-actions", "type": 301 }, { "source": "/to/publish-with-service-account", "destination": "/tools/pub/automated-publishing#publishing-from-google-cloud-build", "type": 301 }, + { "source": "/to/pubspec-overrides", "destination": "/tools/pub/dependencies#pubspec-overrides", "type": 301 }, { "source": "/to/sdk-constraint", "destination": "/tools/pub/pubspec#sdk-constraints", "type": 301 }, { "source": "/to/sdk-version-pinning", "destination": "https://github.com/dart-lang/sdk/blob/main/docs/Flutter-Pinned-Packages.md", "type": 301 }, { "source": "/to/web-debug-extension", "destination": "https://chromewebstore.google.com/detail/dart-debug-extension/eljbmlghnomdjgdjmbdekegdkbabckhm", "type": 301 },