---
title: Automated releases
description: Version packages and publish them to pub.dev from Conventional Commits.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://melos.invertase.dev/llms.txt
> Use this file to discover all available pages before exploring further.

Melos can automate versioning and publishing of your packages.

Automation covers the following:

- Incrementing versions based on commit messages.
- Updating version constraints of dependents.
- Generating changelogs.
- Running versioning hook scripts.
- Updating package version tags in git dependencies.
- Publishing packages to [pub.dev](https://pub.dev).

## Versioning

Melos can version packages automatically based on their commit history. For
automatic versioning to work, Melos needs to parse commit messages and detect
exactly what sort of version upgrade is required. Melos understands
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), a widely
used specification for commit messages that are readable by humans and
machines.

Alternatively, you can version packages manually by specifying a version
increase (`major`, `minor`, `patch`, or `build`) or an exact version.

For more information about customizing the versioning process, see the
[configuration options](/configuration/overview#commandversion) for the
`version` command.

By default, Melos versions each package independently. If you want all packages
in the workspace to always share the same version, enable the
[fixed versioning mode](/reference/commands/version#fixed-versioning-mode).

### Automatic versioning

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

1. Apply [filters](/filters) to the list of workspace packages.
2. Load the commit history for each package. If the `--diff` option is
   specified, Melos loads only the specified commit. Otherwise, Melos loads
   all commits after the last version tag. Examples include `package_name-v1.0.0`,
   or `v1.0.0` for the root package when `useRootAsPackage` is enabled, and for
   all packages when `workspaceTag` is enabled in fixed versioning mode.
3. Parse commit messages as Conventional Commits. If a commit message does not
   follow the Conventional Commits specification, Melos ignores it.
4. Filter out commits with types that don't trigger a version bump. For example,
   Melos ignores `chore` commits.
5. If at this point no commits remain, Melos does not version the package.
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, Melos versions the package with a
   `minor` upgrade.

#### Conventional Commits

The following commit types trigger a version bump:

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

`docs` commits (documentation changes) do not trigger a version bump on their
own, but they are listed in the changelog when the package is versioned.

The first matching rule in the following list determines the version bump for a
commit:

1. A breaking change triggers a `major` version bump.
2. A feature triggers a `minor` version bump.
3. All other changes trigger a `patch` version bump.

Melos supports prefixes (like `Merge ...` and `Merged ...` for example) before
the conventional commit type. Prefix support helps when collaborative version
control systems add these non-configurable prefixes as they merge pull
requests.

#### Versions below 1.0.0

Semantic versioning does not promise compatibility before `1.0.0`. The Dart
community still treats those versions semantically, with each number shifted
down one slot:

- A `major` (breaking) bump increments the minor: `0.1.2` → `0.2.0`.
- A `minor` (feature) bump increments the patch: `0.1.2` → `0.1.3`.
- A `patch` bump also increments the patch: `0.1.2` → `0.1.3`.

#### Build numbers

A version may carry a build number, the `+N` suffix (for example `3.0.0+11`). When
a package's current version has an integer build number, Melos retains it. Melos
increments that build number by one on every version bump, regardless of bump
type:

- `3.0.0+11` with a `major` bump → `4.0.0+12`
- `3.0.0+11` with a `patch` bump → `3.0.1+12`

If the current version has no build number, none is added (for example `3.0.0` →
`3.0.1`). Build metadata that is not a single integer (such as a prerelease-style
tag, a git hash, or a dot-separated build) is not retained:

- `3.0.0+abc` with a `major` bump → `4.0.0`

#### Not using Conventional Commits?

You can still adopt Conventional Commits in an existing Git project and use
Melos for later releases.

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](/guides/automated-releases#manual-versioning). Manual versioning
sets a version increment appropriate for all commits, including commits Melos
cannot interpret.

After you manually version every package at least once, you can 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:

```sh
melos version PACKAGE_NAME VERSION_CHANGE
```

To manually version multiple packages, use the `--manual-version` (short `-V`)
option:

```sh
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
```

When you use `--manual-version`, Melos still runs automatic versioning for other
packages. You can mix automatic and manual versioning. Pass `--ignore '*'` to
exclude all packages from automatic versioning. For more information, see
[`--ignore`](/filters#--ignore).

### Dependents versioning

By default, Melos also updates the constraints in the `pubspec.yaml` files of
dependents of the packages that were versioned. Pass
`--no-dependent-constraints` to disable constraint updates.

If Melos is not already versioning that dependent, it creates a `patch`
version bump for it. Pass `--no-dependent-versions` to disable dependent version
bumps.

Melos does not apply the specified package filters to dependents of versioned
packages.

### Commit and tag version changes

After updating the `pubspec.yaml` files and changelogs of the versioned
packages, Melos commits the changes and adds a package version tag for each
package.

Package version tags have the format `PACKAGE_NAME-vVERSION`.

Pass `--no-git-tag-version` to skip creating tags; Melos still creates the
version commit. Pass `--no-git-commit-version` to skip the commit as well (that
flag also implies `--no-git-tag-version`).

#### Hook

After updating `pubspec.yaml` files and changelogs but before creating the
version commit, Melos runs the `command/version/hooks/preCommit` script in the
root `pubspec.yaml` file. Use the hook to run custom code before Melos creates
the version commit.

Stage any hook changes yourself if you want them in the version commit.

### Changelog

Melos updates the changelog for each package that is versioned by prepending a
section for the new version. Pass `--no-changelog` to skip changelog updates.

For more information about customizing changelog generation, see the
configuration options for the `version` command.

Melos can also write a
[workspace changelog](/configuration/overview#workspacechangelog). Melos enables
the workspace changelog by default.

## Publishing

Before you publish packages on [pub.dev](https://pub.dev), confirm the following:

1. Confirm you have permission to publish all the packages.
2. Authenticate the machine with Pub.

<Info>Internally, Melos uses `pub publish` to publish the packages.</Info>

After you finish [versioning](/guides/automated-releases#versioning) your packages,
run `melos publish` to preview pending publishes:

```sh
melos publish
```

By default, Melos performs a dry-run and does not publish anything.

When you are satisfied with your pending releases, publish them to
[pub.dev](https://pub.dev):

```sh
melos publish --no-dry-run
```

## Releases

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

To enable release URLs for a single run, pass one of these arguments to
`melos version`:

```sh
melos version --release-url
melos version -r
```

To enable release URLs permanently, add the following to your root
`pubspec.yaml` file:

```yaml
melos:
  command:
    version:
      releaseUrl: true
```

## Git hosted packages

If your packages are private and you do not publish them to
[pub.dev](https://pub.dev), use package version tags as git references in your
`pubspec.yaml` files. Melos updates those tags accordingly.

To use this feature, enable
[`command/version/updateGitTagRefs`](/configuration/overview#updategittagrefs)
in your root `pubspec.yaml` file.

Take the following git dependency:

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

When you create a patch release for `internal_dep` with `melos version`, Melos
updates the `ref` to the new version:

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