Migrating to Melos 8.x
Melos 7 moved to pub workspaces and
Melos 8 changed the exec script format. Melos 8.x requires Dart 3.9.0 or
newer. Melos reports a descriptive error, including the converted
configuration, when it finds the old exec format.
Guidelines
- Do the whole migration in one change:
melos.yamland the oldexecformat cannot be mixed with the new layout. - Run
melos cleanwith the old Melos version first, to remove the generatedpubspec_overrides.yamlfiles, then upgrade. - Keep the content of the old
melos.yamlexceptnameandpackages; it moves undermelos:in the rootpubspec.yamlunchanged, apart from the script and hook changes below. - Add
resolution: workspaceto every packagepubspec.yaml. - After the migration run
melos bootstrapand commit the rootpubspec.lock.
6.x (or older) to 8.x
Before:
# melos.yaml
name: my_workspace
packages:
- packages/**
scripts:
test:
run: dart test
exec:
concurrency: 1
select-package:
dir-exists: test
After, root pubspec.yaml:
name: my_workspace
publish_to: none
environment:
sdk: ^3.9.0
workspace:
- packages/helper
- packages/client
dev_dependencies:
melos: ^8.0.0
melos:
scripts:
test:
exec:
command: dart test
concurrency: 1
packageFilters:
dirExists: test
Each package pubspec.yaml:
name: helper
environment:
sdk: ^3.9.0
resolution: workspace
Steps:
melos cleanto remove thepubspec_overrides.yamlfiles.- Create or update the root
pubspec.yamlwithworkspace:, themelosdev dependency and themelos:section. - Add
resolution: workspaceto every package. - Delete
melos.yaml. - Convert the scripts as described below.
melos bootstrap.
workspace: supports globs from Dart 3.11; on older SDKs list each package.
Root package
Melos 6 allowed . in packages:. In Melos 7+ either set
useRootAsPackage: true in the melos section, or move the root app into a
subdirectory and add it to workspace:.
7.x to 8.x
exec scripts
run and exec are mutually exclusive. Move the command into exec under
command:
# Before (rejected by Melos 8)
test:
run: dart test --concurrency=1
exec:
concurrency: 1
# After
test:
exec:
command: dart test --concurrency=1
concurrency: 1
A string exec is unchanged: exec: dart test.
Build numbers
melos version now keeps and increments an integer build number
(3.0.0+11 becomes 4.0.0+12), and a patch release below 1.0.0 bumps the
patch component (0.1.0 becomes 0.1.1, not 0.1.0+1).
melos analyze
Removed in 7.0.0, restored in 8.1.0 with support for all package filters.
Older formats still found in the wild
Melos 2 to 3:
- Hooks were scripts named after the command. They are now
command/<name>/hooks/preandpost:bootstraptocommand/bootstrap/hooks/pre,postbootstraptocommand/bootstrap/hooks/post,cleanandpostcleanlikewise,versiontocommand/version/hooks/preCommit,postversiontocommand/version/hooks/post. select-packagewas renamed topackageFiltersand its filter names are camel cased (dir-existstodirExists).--sincewas replaced by--diff.command/bootstrap/usePubspecOverrideswas removed.includeScopes,linkToCommits(whenrepositoryis set) andworkspaceChangelogdefault totrue.
Melos 3 to 4:
--no-git-tag-versionno longer skips the commit; add--no-git-commit-versionfor that.
Checklist
- No
melos.yamlin the repository. - Root
pubspec.yamlhasworkspace:,dev_dependencies: melosand amelos:section. - Every package has
resolution: workspace. - No
pubspec_overrides.yamlgenerated by Melos in the packages (removepubspec_overrides.yamlfrom.gitignoreonly if nothing else uses it). - No script has both
runand anexecmap. - No
select-package, no kebab case filter names. - Hooks live under
command/<name>/hooks. -
melos bootstrapsucceeds andpubspec.lockis committed.
References
- Migrations guide: https://melos.invertase.dev/~melos-latest/migration
- Configuration overview: https://melos.invertase.dev/~melos-latest/configuration/overview