Migrations

2.0.0 to 3.0.0#

Versioning of Melos in workspaces#

From Melos 3.0.0, the version of Melos to use in any given workspace must be specified in a pubspec.yaml file next to the melos.yaml file, in the workspace root directory.

Different Melos workspaces might use different versions of Melos. To ensure everyone working in the workspace (as well as CI jobs) is using the same version of Melos, a dependency on the melos package has to be added to the pubspec.yaml file at the workspace root directory. The globally installed version of Melos will switch to the version specified in the pubspec.yaml file, if both versions are not the same.

If you don't have a pubspec.yaml file at the workspace root yet, create one now:

name: <project>_workspace

environment:
  sdk: '>=2.18.0 <3.0.0'

The corresponding pubspec.lock file should also be committed. Make sure to exclude it from the .gitignore file.

Add Melos as a development dependency by running the following command:

dart pub add melos --dev

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).

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

--since was removed in favour of --diff#

The --since flag was removed in favour of --diff, which is more flexible and can be used to specify a range of commits in addition to a single commit.

To migrate from --since to --diff simply replace --since with --diff.

Options that are now enabled by default#

The following options which were previously set to false by default are now set to true by default:

  • command/version/includeScopes
  • command/version/linkToCommits, if repository is configured
  • command/version/workspaceChangelog

Lifecycle hooks#

The lifecycle pre and post hooks have been renamed. Previously, the pre hook had the same name as the command, and the post hook had the name of the command with post appended. Now, both the pre and post hook names are the capitalized name of the command, prefixed with pre or post respectively.

  • bootstrap -> preBootstrap
  • postbootstrap -> postBootstrap
  • clean -> preClean
  • postclean -> postClean
  • version -> preVersion
  • postversion -> postVersion

The version hook was previously executed during versioning, before the version commit was created. The preVersion hook is now executed before the version command, like for all other commands.

The new preVersionCommmit hook is executed before the version commit is created and is the equivalent of the previous version hook.

Package filters#

The select-package option for scripts has been renamed to packageFilters. This brings it in line with command/version/changelogs/packageFilters.

The names of filters specified in packageFilters are now camel cased instead of kebab cased.

For example, take the following test script configuration:

scripts:
  test:
    exec: dart test
    packageFilters:
      dirExists: test

This would previously have been written as:

scripts:
  test:
    exec: dart test
    select-package:
      dir-exists: test