LogoMelos

Automated Releases

Melos is able to automate versioning and publishing of your packages.

This includes:

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

Versioning#

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 increase (major, minor, patch or build) or an exact version.

For customizing the versioning process, see the configuration options for the version command.

Automatic Versioning#

To determine which packages to version and how, Melos performs the following steps:

  1. Apply filters to the list of workspace packages.
  2. Load the commit history for each package. If the --diff option is specified, Melos will only load the specified commit. Otherwise it will load all commits since the last version tag (e.g. foo-v1.0.0).
  3. Parse commit messages as Conventional Commits. If a commit message does not follow the Conventional Commits specification, it will be ignored.
  4. Filter out commits with types that don't trigger a version bump. For example, chore commits will be ignored.
  5. If at this point no commits remain, the package will not be versioned.
  6. 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 feat commit and a fix commit, the package will be versioned with a minor upgrade.

Conventional Commits#

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:

  1. A breaking change will trigger a major version bump.
  2. A feature will trigger a minor version bump.
  3. 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 requests.

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#

Manual versioning allows you to specify a version increment (major, minor, patch or 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 --manual-version (short -V) option:

melos version --manual-version <package-1-name>:<version-change> --manual-version <package-2-name>:<version-change>
# Same but with short version
melos version -V <package-1-name>:<version-change> -V <package-2-name>:<version-change>

Note that when using the --manual-version option, the automatic versioning process is executed normally, except for the packages that are manually versioned. It allows to mix automatic and manual versioning. The --ignore filter can be used to exclude all packages from automatic versioning, by passing --ignore '*'.

Dependents Versioning#

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 --no-dependent-constraints.

If such a dependent is not already being versioned, a patch version bump will be created for it. This can be disabled by passing --no-dependent-versions.

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.

Package version tags have the format <package-name>-v<version>.

This behavior can be disabled by passing --no-git-tag-version.

Hook#

After updating pubspec.yaml files and changelogs but before creating the version commit, the command/version/hooks/preCommit script in melos.yaml is executed. This allows you to run custom code before the version commit is created.

Note that you have to stage changes that you make in the hook and want to have included in the version commit yourself.

Changelog#

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 --no-changelog.

See the configuration options for the version command for customizing changelog generation.

Melos can also write a workspace changelog. This is enabled by default.

Publishing#

To publish packages on pub.dev you must:

  1. Have permission to publish all the packages.
  2. Be on a machine which is authenticated with Pub.
Internally, Melos uses pub publish to publish the packages.

Once you have versioned your packages, run the publish command to check everything is good to go:

melos publish

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

Releases#

Melos can generate a link to the prefilled release creation page.

To enable this once use one of the following arguments to melos version:

melos version --release-url
melos version -r

To enable this feature permanently, add the following to your melos.yaml:

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 your pubspec.yaml files and Melos will ensure that the tags are updated accordingly.

To use this feature enable command/version/updateGitTagRefs in melos.yaml

Take the following git dependency:

dependencies:
  internal_dep:
    git:
      url: git@github.com:org/repo.git
      path: packages/internal_dep
      ref: internal_dep-v0.0.1

When creating a patch release for internal_dep through melos version the ref would be updated to the new version:

dependencies:
  internal_dep:
    git:
      url: git@github.com:org/repo.git
      path: packages/internal_dep
      ref: internal_dep-v0.0.2