Melos is able to automate versioning and publishing of your packages.
- incrementing of versions based on commit messages.
- updating version constraints of dependents.
- generating of changelogs.
- running versioning hook scripts.
- update package version tags in git dependencies.
- publishing of packages to pub.dev.
Packages can be versioned automatically based on their commit history. For this to work, Melos needs to be able to parse commit messages and detect exactly what sort of version upgrade is required. Melos understands Conventional Commits, a widely used specification for commit messages which are readable by humans and machines.
Alternatively, packages can be versioned manually by specifing a version
build) or an exact version.
For customizing the versioning process, see the
configuration options for the
To determine which packages to version and how, Melos performs the following steps:
- Apply filters to the list of workspace packages.
- Load the commit history for each package. If the
--diffoption is specified, Melos will only load the specified commit. Otherwise it will load all commits since the last version tag (e.g.
- Parse commit messages as Conventional Commits. If a commit message does not follow the Conventional Commits specification, it will be ignored.
- Filter out commits with types that don't trigger a version bump. For example,
chorecommits will be ignored.
- If at this point no commits remain, the package will not be versioned.
- Determine the version upgrade required for each package based on the commit
with the most significant version bump. For example, if a package has a
featcommit and a
fixcommit, the package will be versioned with a
Currently the following commit types trigger a version bump:
docs- A documentation change.
feat- A new feature.
fix- A bug fix.
bug- A bug fix.
perf- A change that improves performance.
refactor- A change that neither fixes a bug nor adds a feature.
revert- A change that reverts a previous commit.
The first matching rule in the list below determines the version bump for a commit:
- A breaking change will trigger a major version bump.
- A feature will trigger a minor version bump.
- All other changes will trigger a patch version bump.
Melos supports prefixes (like
Merge ... and
Merged ... for example) before
the conventional commit type. This is useful since some collaborative version
control systems use these non-configurable prefixes when they merge pull
Not using Conventional Commits?#
If an existing Git project is already established and does not use Conventional Commits, it is still possible to adopt the convention and use Melos for future releases.
Just start writing commit messages that follow Conventional Commits. When you are ready to release a package for the first time with Melos use manual versioning. This will ensure that the version increment is appropriate for all commits, including those that Melos cannot interpret.
Once you have manullay versioning every packages at least once, you can savely use automatic versioning.
Manual versioning allows you to specify a version increment (
build) or an exact version for one or more packages.
If you only want to manually version a single package, you can use the following syntax:
melos version <package-name> <version-change>
To manually version multiple packages use the
melos version --manual-version <package-name>:<version-change>
Note that when using the
--manual-version option, the automatic versioning
process is executed normally, execpt for the packages that are manually
versioned. This allows you to mix automatic and manual versioning. The
--ignore filter can be used to exclude all package from
automatic versioning, by passing
By default, Melos also updates the constraints in the
pubspec.yaml files of
dependents of the packages that were versioned. This can be disabled by passing
If such a dependent is not already being versioned, a patch version bump
will be created for it. This can be disabled by passing
Note that dependents of versioned packages are not filtered by the specified package filters.
Committing and Tagging Version Changes#
After updating the
pubspec.yaml files and changelogs of the versioned
packages, Melos will commit the changes and add a package version tag for each
Package version tags have the format
This behavior can be disabled by passing
pubspec.yaml files and changelogs but before creating the
version commit, the
command/version/hooks/preCommit script in
executed. This allows you to run custom code before the version commit is
Note that you have to stage changes that you make in the hook and want to have included in the version commit yourself.
Melos updates the changelog for each package that is versioned by prepending a
section for the new version. You can disable this behavior by passing
See the configuration options for the
version command for customizing changelog generation.
Melos can also write a workspace changelog. This is enabled by default.
To publish packages on pub.dev you must:
- Have permission to publish all the packages.
- Be on a machine which is authenticated with Pub.
pub publishto publish the packages.
Once you have versioned your packages, run the publish command to check everything is good to go:
By default, a dry-run is performed (nothing will be published).
Once satisfied with your pending releases, release them to pub.dev:
melos publish --no-dry-run
Melos can generate a link to the prefilled release creation page.
To enable this once use one of the following arguments to
melos version --release-url melos version -r
To enable this feature permanently, add the following to your
command: version: releaseUrl: true
Git Hosted Packages#
If your packages are private and you don't publish them to
pub.dev, you can use package version tags as git reference in
pubspec.yaml files and Melos will ensure that the tags are updated
To use this feature enable
Take the following git dependency:
dependencies: internal_dep: git: url: email@example.com:org/repo.git path: packages/internal_dep ref: internal_dep-v0.0.1
When creating a patch release for
melos version the
ref would be updated to the new version:
dependencies: internal_dep: git: url: firstname.lastname@example.org:org/repo.git path: packages/internal_dep ref: internal_dep-v0.0.2