invertase · blaugold · Dec 8, 2022 · Dec 7, 2022 · Dec 8, 2022 · Dec 8, 2022
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@
 
 
 <p align="center">
-  <a href="https://melos.invertase.dev">Documentation</a> &bull; 
+  <a href="https://melos.invertase.dev">Documentation</a> &bull;
   <a href="https://github.com/invertase/melos/blob/main/LICENSE">License</a>
 </p>
 
@@ -36,7 +36,7 @@ To solve these (and many other) problems, some projects will organize their code
   - Can be combined with all package filters.
 - 🎯 Many advanced package filtering options allowing you to target specific packages or groups of packages in your workspace.
 - ♨️ Advanced support for IntelliJ IDEs with automatic creation of [run configurations for workspace defined scripts and more](https://github.com/invertase/melos/issues/9) on workspace bootstrap.
-  - Vscode code doesn't require advanced integration to work.
+  - Integration with VS Code through an [extension][melos-code].
 
 ## Install
 
@@ -68,3 +68,5 @@ Using Melos? Add a README badge to show it off:
     Built and maintained by <a href="https://invertase.io/?utm_source=readme&utm_medium=footer&utm_campaign=melos">Invertase</a>.
   </p>
 </p>
+
+[melos-code]: https://marketplace.visualstudio.com/items?itemName=blaugold.melos-code
diff --git a/docs.json b/docs.json
@@ -37,7 +37,8 @@
           "Manage multi-package Flutter projects",
           "https://sagarsuri56.medium.com/managing-multi-package-flutter-projects-with-melos-c8ce96fa7c82"
         ],
-        ["Automated Releases", "/guides/automated-releases"]
+        ["Automated Releases", "/guides/automated-releases"],
+        ["Migrations", "/guides/migrations"]
       ]
     ]
   ]

diff --git a/docs/configuration/overview.mdx b/docs/configuration/overview.mdx
@@ -155,19 +155,6 @@ Configuration relating to specific Melos commands such as versioning.
 
 Configuration for the `bootstrap` command.
 
-### `command/bootstrap/usePubspecOverrides`
-
-Whether to use `pubspec_overrides.yaml` for overriding workspace dependencies
-during development.
-
-When this option is enabled, Melos will generate a `pubspec_overrides.yaml` file
-in the root of every package during bootstrapping. This file should not be
-tracked in version control and should be added to `.gitignore`.
-
-This mechanism has the advantage that it does not conflict with other tooling
-such as the `dart` and `flutter` tools and IDE plugins, when compared to the
-original mechanism used to link local packages.
-
 ### `command/bootstrap/runPubGetInParallel`
 
 Whether to run `pub get` in parallel during bootstrapping.

diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
@@ -31,18 +31,12 @@ packages:
 The `packages` list should contain paths to the individual packages within your project. Each path
 can be defined using the [glob](https://docs.python.org/3/library/glob.html) pattern expansion format.
 
-Consider setting `usePubspecOverrides` to `true`:
+Melos generates `pubspec_overrides.yaml` files to link local packages for development. Typically these files
+should be ignored by git. To ignore these files, add the following to your `.gitignore` file:
 
-```yaml
-command:
-  bootstrap:
-    usePubspecOverrides: true
 ```
-
-This enables a new mechanism for linking local packages, which integrates better with other tooling
-(e.g. `dart` tool, `flutter` tool, IDE plugins) than the mechanism currently being used
-by default. Please read the documentation for [`usePubspecOverrides`](/configuration/overview#commandbootstrapusepubspecoverrides)
-before enabling this feature.
+pubspec_overrides.yaml
+```
 
 ## Bootstrapping
 
@@ -84,6 +78,6 @@ scripts:
 Then execute the command by running `melos run analyze`.
 
 If you're looking for some inspiration as to what scripts can help with, check out the
-[FlutterFire repository](https://github.com/FirebaseExtended/flutterfire/blob/master/melos.yaml).
+[FlutterFire repository](https://github.com/firebase/flutterfire/blob/master/melos.yaml).
 
 If you are using VS Code, there is an [extension](/ide-support#vs-code) available, to integrate Melos with VS Code.
diff --git a/docs/guides/migrations.mdx b/docs/guides/migrations.mdx
@@ -0,0 +1,31 @@
+---
+title: Migrations
+description: How to migrate between major versions of Melos.
+---
+
+# Migrations
+
+## 2.0.0 to 3.0.0
+
+### Local package linking with `pubspec_overrides.yaml`
+
+The initial mechanism used by Melos to link local packages for development had
+some issues when interacting with other tooling. An often-encountered error is
+"The pubspec.yaml file has changed since the pubspec.lock file was generated"
+([#117](https://github.com/invertase/melos/issues/117)).
+
+To resolve this issue, an alternative mechanism has been implemented which
+generates `pubspec_overrides.yaml` files in the root of each package, for which
+dependencies need to be overridden. Before Melos 3.0.0, this mechanism had to be
+opted into by setting `command/bootstrap/usePubspecOverrides` in `melos.yaml` to
+`true`.
+
+This is now the only mechanism used by Melos and the `usePubspecOverrides`
+configuration option has been removed.
+
+Typically `pubspec_overrides.yaml` files should be ignored by git. To ignore
+these files, add the following to your `.gitignore` file:
+
+```
+pubspec_overrides.yaml
+```
diff --git a/docs/ide-support.mdx b/docs/ide-support.mdx
@@ -33,7 +33,7 @@ Melos scripts are provided as VS Code tasks:
 
 ![Tasks provided to VS Code](/assets/vs-code-melos-tasks.png)
 
-To configure a task that run a Melos script, use task type `melos`:
+To configure a task that runs a Melos script, use task type `melos`:
 
 ```json
 // .vscode/tasks.json

diff --git a/docs/index.mdx b/docs/index.mdx
@@ -43,7 +43,7 @@ The following projects are using Melos:
 - [rrifafauzikomara/youtube_video](https://github.com/rrifafauzikomara/youtube_video)
 
 > Submit a PR if you'd like to add your project to the list.
-> Update the 
+> Update the
 > [docs](https://github.com/invertase/melos/edit/main/docs/index.mdx).
 
 ## License

diff --git a/melos.yaml b/melos.yaml
@@ -12,8 +12,6 @@ command:
     branch: main
     # Additionally build a changelog at the root of the workspace.
     workspaceChangelog: true
-  bootstrap:
-    usePubspecOverrides: true
 
 ide:
   intellij: true

diff --git a/packages/melos/README.md b/packages/melos/README.md
@@ -7,15 +7,17 @@
 
 ## About
 
-Splitting up large code bases into separate independently versioned packages is extremely useful for code sharing.
-However, making changes across many repositories is _messy_ and difficult to track, and testing across repositories gets
-complicated really fast.
+Splitting up large code bases into separate independently versioned packages is
+extremely useful for code sharing. However, making changes across many
+repositories is _messy_ and difficult to track, and testing across repositories
+gets complicated really fast.
 
 To solve these (and many other) problems, some projects will organize their code
 bases into multi-package repositories (sometimes called
 [monorepos](https://en.wikipedia.org/wiki/Monorepo))
 
-**Melos is a tool that optimizes the workflow around managing multi-package repositories with git and Pub.**
+**Melos is a tool that optimizes the workflow around managing multi-package
+repositories with git and Pub.**
 
 ---
 
@@ -33,56 +35,66 @@ my-melos-repo/
       pubspec.yaml
 ```
 
-The location of your packages can be configured via the `melos.yaml` configuration file if the default is unsuitable.
+The location of your packages can be configured via the `melos.yaml`
+configuration file if the default is unsuitable.
 
 ---
 
 ### What can Melos do?
 
-- 🔗 Link local packages in your workspace together without adding dependency overrides.
-- 📦 Automatically version, create changelogs and publish your packages
-  using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
-- 📜 Pre-define advanced custom scripts for your workspace in your `melos.yaml` configuration to use
-  via `melos run [scriptName]`. Anyone contributing to your workspace can just run `melos run` to be prompted to select
-  a script from a list with descriptions of each script.
-    - Scripts can even [prompt to select a package](https://github.com/invertase/melos/pull/34) to run against with
-      pre-defined filters.
-- ⚡ Execute commands across your packages easily with `melos exec -- command here` with additional concurrency and
-  fail-fast options.
-    - [Environment variables](https://github.com/invertase/melos/issues/3) containing various information about the
-      current package and the workspace are available in each execution.
-    - Can be combined with all package filters.
-- 🎯 Many advanced package filtering options allowing you to target specific packages or groups of packages in your
-  workspace.
-    - `--no-private`
-        - Exclude private packages (`publish_to: none`).
-    - `--[no-]published`
-        - Filter packages where the current local package version exists on pub.dev. Or "-no-published" to filter
-          packages that have not had their current version published yet.
-    - `--[no-]nullsafety`
-        - Filter packages where the current local version uses a "nullsafety" prerelease preid. Or "-no-nullsafety" to
-          filter packages where their current version does not have a "nullsafety" preid.
-    - `--[no-]flutter`
-        - Filter packages where the package depends on the Flutter SDK. Or "-no-flutter" to filter packages that do not
-          depend on the Flutter SDK.
-    - `--scope=<glob>`
-        - Include only packages with names matching the given glob.
-    - `--ignore=<glob>`
-        - Exclude packages with names matching the given glob.
-    - `--since=<ref>`
-        - Only include packages that have been changed since the specified `ref`, e.g. a commit sha or git tag.
-    - `--dir-exists=<dirRelativeToPackageRoot>`
-        - Include only packages where a specific directory exists inside the package.
-    - `--file-exists=<fileRelativeToPackageRoot>`
-        - Include only packages where a specific file exists in the package.
-    - `--depends-on=<dependantPackageName>`
-        - Include only packages that depend on a specific package.
-    - `--no-depends-on=<noDependantPackageName>`
-        - Include only packages that *don't* depend on a specific package.
-- ♨️ Advanced support for IntelliJ IDEs with automatic creation
-  of [run configurations for workspace defined scripts and more](https://github.com/invertase/melos/issues/9) on
-  workspace boostrap.
-    - Vscode code doesn't require advanced integration to work.
+- 🔗 Link local packages in your workspace together without adding dependency
+  overrides.
+- 📦 Automatically version, create changelogs and publish your packages using
+  [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+- 📜 Pre-define advanced custom scripts for your workspace in your `melos.yaml`
+  configuration to use via `melos run [scriptName]`. Anyone contributing to your
+  workspace can just run `melos run` to be prompted to select a script from a
+  list with descriptions of each script.
+  - Scripts can even
+    [prompt to select a package](https://github.com/invertase/melos/pull/34) to
+    run against with pre-defined filters.
+- ⚡ Execute commands across your packages easily with
+  `melos exec -- command here` with additional concurrency and fail-fast
+  options.
+  - [Environment variables](https://github.com/invertase/melos/issues/3)
+    containing various information about the current package and the workspace
+    are available in each execution.
+  - Can be combined with all package filters.
+- 🎯 Many advanced package filtering options allowing you to target specific
+  packages or groups of packages in your workspace.
+  - `--no-private`
+    - Exclude private packages (`publish_to: none`).
+  - `--[no-]published`
+    - Filter packages where the current local package version exists on pub.dev.
+      Or "-no-published" to filter packages that have not had their current
+      version published yet.
+  - `--[no-]nullsafety`
+    - Filter packages where the current local version uses a "nullsafety"
+      prerelease preid. Or "-no-nullsafety" to filter packages where their
+      current version does not have a "nullsafety" preid.
+  - `--[no-]flutter`
+    - Filter packages where the package depends on the Flutter SDK. Or
+      "-no-flutter" to filter packages that do not depend on the Flutter SDK.
+  - `--scope=<glob>`
+    - Include only packages with names matching the given glob.
+  - `--ignore=<glob>`
+    - Exclude packages with names matching the given glob.
+  - `--since=<ref>`
+    - Only include packages that have been changed since the specified `ref`,
+      e.g. a commit sha or git tag.
+  - `--dir-exists=<dirRelativeToPackageRoot>`
+    - Include only packages where a specific directory exists inside the
+      package.
+  - `--file-exists=<fileRelativeToPackageRoot>`
+    - Include only packages where a specific file exists in the package.
+  - `--depends-on=<dependantPackageName>`
+    - Include only packages that depend on a specific package.
+  - `--no-depends-on=<noDependantPackageName>`
+    - Include only packages that _don't_ depend on a specific package.
+- ♨️ Advanced support for IntelliJ IDEs with automatic creation of
+  [run configurations for workspace defined scripts and more](https://github.com/invertase/melos/issues/9)
+  on workspace bootstrap.
+  - Integration with VS Code through an [extension][melos-code].
 
 ---
 
@@ -109,16 +121,18 @@ The following projects are using Melos:
 - [ferraridamiano/ConverterNOW](https://github.com/ferraridamiano/ConverterNOW)
 - [rrifafauzikomara/youtube_video](https://github.com/rrifafauzikomara/youtube_video)
 
-> Submit a PR if you'd like to add your project to the list.
-> Update the [README.md](https://github.com/invertase/melos/edit/main/packages/melos/README.md) and the
-> [docs](https://github.com/invertase/melos/edit/main/docs/index.mdx).
-> You can also add a [readme badge](#readme-badge) to your projects readme to let others know about Melos 💙.
+> Submit a PR if you'd like to add your project to the list. Update the
+> [README.md](https://github.com/invertase/melos/edit/main/packages/melos/README.md)
+> and the [docs](https://github.com/invertase/melos/edit/main/docs/index.mdx).
+> You can also add a [readme badge](#readme-badge) to your projects readme to
+> let others know about Melos 💙.
 
 ---
 
 ## Getting Started
 
-Install the latest Melos version as a global package via [Pub](https://pub.dev/).
+Install the latest Melos version as a global package via
+[Pub](https://pub.dev/).
 
 ```bash
 dart pub global activate melos
@@ -131,7 +145,15 @@ dart pub global activate melos
 
 ### Documentation
 
-Documentation is available at [https://docs.page/invertase/melos](https://docs.page/invertase/melos).
+Documentation is available at
+[https://melos.invertase.dev](https://melos.invertase.dev).
+
+---
+
+### Migrations
+
+When migrating between major versions of Melos, please read the
+[migration guide](https://melos.invertase.dev/guides/migrations).
 
 ---
 
@@ -147,18 +169,9 @@ A CLI tool for managing Dart & Flutter projects with multiple packages.
 Usage: melos <command> [arguments]
 
 Global options:
--h, --help                                       Print this usage information.
-    --verbose                                    Enable verbose logging.
-    --no-private                                 Exclude private packages (`publish_to: none`). They are included by default.
-    --[no-]published                             Filter packages where the current local package version exists on pub.dev. Or "-no-published" to filter packages that have not had their current version published yet.
-    --[no-]flutter                               Filter packages where the package depends on the Flutter SDK. Or "-no-flutter" to filter packages that do not depend on the Flutter SDK.
-    --scope=<glob>                               Include only packages with names matching the given glob. This option can be repeated.
-    --ignore=<glob>                              Exclude packages with names matching the given glob. This option can be repeated.
-    --since=<ref>                                Only include packages that have been changed since the specified `ref`, e.g. a commit sha or git tag.
-    --dir-exists=<dirRelativeToPackageRoot>      Include only packages where a specific directory exists inside the package.
-    --file-exists=<fileRelativeToPackageRoot>    Include only packages where a specific file exists in the package.
-    --depends-on=<dependantPackageName>          Include only packages that depend on a specific package. This option can be repeated.
-    --no-depends-on=<noDependantPackageName>     Include only packages that *don't* depend on a specific package. This option can be repeated.
+-h, --help        Print this usage information.
+    --verbose     Enable verbose logging.
+    --sdk-path    Path to the Dart/Flutter SDK that should be used. This command line option has precedence over the `sdkPath` option in the `melos.yaml` configuration file and the `MELOS_SDK_PATH` environment variable. To use the system-wide SDK, provide the special value "auto".
 
 Available commands:
   bootstrap   Initialize the workspace, link local packages together and install remaining package dependencies. Supports all package filtering options.
@@ -209,3 +222,6 @@ Using Melos? Add a README badge to show it off:
 </p>
 
 ---
+
+[melos-code]:
+  https://marketplace.visualstudio.com/items?itemName=blaugold.melos-code
diff --git a/packages/melos/example/README.md b/packages/melos/example/README.md
@@ -1,3 +1,4 @@
 # Melos Example
 
-> See the [documentation](https://docs.page/invertase/melos) for example project structures.
+> See the [documentation](https://melos.invertase.dev) for example project
+> structures.