# Versioning & Releases (/docs/developer-guide/releases)



## Changesets [#changesets]

Elmo uses [Changesets](https://github.com/changesets/changesets) for version management. All packages in the monorepo use fixed versioning — they stay on the same version number.

### Adding a Changeset [#adding-a-changeset]

Every PR that changes user-facing behavior should include a changeset:

```bash
pnpm changeset
```

This interactive command asks:

. Which packages are affected
. Whether the change is a major, minor, or patch
. A short description of what changed

A markdown file is created in the `.changeset/` directory. Commit this file with your PR.

### What Needs a Changeset [#what-needs-a-changeset]

* Bug fixes → `patch`
* New features → `minor`
* Breaking changes → `major`
* Documentation-only changes → usually don't need a changeset
* Internal refactors that don't change behavior → usually don't need a changeset

## Release Process (Maintainers) [#release-process-maintainers]

When ready to release a new version:

. **Apply changesets and bump versions** locally:
  ```bash
  pnpm version-packages
  ```
  This consumes all pending changeset files, updates `package.json` versions across the monorepo, and generates `CHANGELOG.md` entries.

. **Review and commit** the version changes:
  ```bash
  git add .
  git commit -m "chore: release v$(node -p "require('./apps/cli/package.json').version")"
  git push
  ```

. **Trigger the release workflow** from GitHub Actions:
  * Go to **Actions → Release → Run workflow**
  * This creates a GitHub release and publishes to Docker Hub and npm

## What Gets Published [#what-gets-published]

| Artifact                 | Registry   | Description                       |
| ------------------------ | ---------- | --------------------------------- |
| `@elmohq/cli`            | npm        | The Elmo CLI package              |
| `elmohq/elmo-web`        | Docker Hub | Web app Docker image              |
| `elmohq/elmo-worker`     | Docker Hub | Worker Docker image               |
| `elmohq/elmo-db-migrate` | Docker Hub | One-shot drizzle migrations image |

## Versioning Strategy [#versioning-strategy]

All packages share the same version number. When any package changes, all versions bump together. This keeps things simple and avoids compatibility issues between packages.