Migrations

3.0.0 to 4.0.0

--no-git-tag-version behavior change

If you were previously using --no-git-tag-version and were relying on that it didn't create a commit you now have to also pass --no-git-commit-version to prevent a commit from being automatically created after versioning.

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: my_project_workspace

environment:
  sdk: '>=3.0.0 <4.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.

Changed option defaults

The following options are now enabled by default:

Lifecycle hooks

Lifecycle hooks have been moved to the respective command configurations. Previously, hooks were defined in scripts. The pre hook had the same name as the command, and the post hook had the name of the command with post appended. Now, hooks are defined in command/<name>/hooks.

  • bootstrap -> command/bootstrap/hooks/pre
  • postbootstrap -> command/bootstrap/hooks/post
  • clean -> command/clean/hooks/pre
  • postclean -> command/clean/hooks/post
  • version -> command/version/hooks/preCommit
  • postversion -> command/version/hooks/post

Version command hooks

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

The new preCommit 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