Migrations

6.x.x to 7.x.x

Since the pub workspaces feature has been released, Melos has been updated to rely on that, instead of creating pubspec_overrides.yaml files and thus some migration is needed.

The main difference is that:

1. There is no longer a melos.yaml file, only the root pubspec.yaml
2. You now have to add resolution: workspace to all of your packages' pubspec.yaml files.
3. You now have to add a list of all your packages to the root pubspec.yaml file.

After the migration your root pubspec.yaml file would now look something like this:

name: my_workspace
publish_to: none
environment:
  sdk: ^3.9.0
workspace:
  - packages/helper
  - packages/client_package
  - packages/server_package
dev_dependencies:
  melos: ^7.0.0

melos:
  # All of the content of your previous melos.yaml file
  # (Except for the packages and name)

And this is what the pubspec.yaml file of a package would look like:

name: my_package
environment:
  sdk: ^3.9.0
resolution: workspace

'melos analyze` no longer exists

Since flutter/dart analyze now runs in the full pub workspace, the melos analyze command has been removed,

Root packages

In Melos 6.x, you could include the repository root (.) as a package in the workspace by listing it in the packages configuration. In Melos 7.x with pub workspaces, this behavior is not supported by default.

If your project uses the repository root as a package, you have two options:

Option 1: Enable useRootAsPackage

Recommended for existing projects.

Add the useRootAsPackage option to maintain existing behavior:

# pubspec.yaml
name: my_workspace
publish_to: none
environment:
  sdk: ^3.9.0
workspace:
  - packages/helper
  - packages/client_package

melos:
  useRootAsPackage: true
  categories:
    app:
      - "."
    packages:
      - "packages/**"

This allows the root package to participate in workspace operations such as scripts, filtering, and categorization.

Option 2: Restructure (Recommended for new projects)

Move your root application into a subdirectory:

1. Create an apps/ or app/ directory
2. Move your main application code there
3. Update your workspace configuration accordingly

This approach provides better separation between workspace configuration and application code.

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:

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

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