Versioning & Releases

How Elmo handles versioning, changesets, and the release process.

Changesets

Elmo uses Changesets for version management. All packages in the monorepo use fixed versioning — they stay on the same version number.

Adding a Changeset

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

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

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)

When ready to release a new version:

Apply changesets and bump versions locally:

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:

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

Artifact	Registry	Description
`@elmohq/cli`	npm	The Elmo CLI package
`elmohq/web`	Docker Hub	Web app Docker image
`elmohq/worker`	Docker Hub	Worker Docker image

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.

Was this page helpful?