Skip to main content
Version: Next

Versioning & Releases

This document explains the versioning strategy for this monorepo and recommendations for managing releases.

Current State​

Currently, the project is in early development. Versions are managed manually in each package.json file. Git tags are not yet implemented for automated release tracking.

Monorepo Versioning Strategies​

We recommend using one of the following strategies for this pnpm monorepo:

1. Fixed (Locked) Versioning​

All packages share the same version number. If one package has a major update, the version of all packages is bumped.

  • Pros: Simplest to understand; ensures compatibility.
  • Cons: Can lead to unnecessary version bumps for stable packages.

2. Independent Versioning​

Each package in apps/ is versioned independently based on its own changes.

  • Pros: More efficient; reflects the actual state of each app.
  • Cons: Harder to track which versions of different apps were tested together.

We highly recommend using Changesets to manage versioning and changelogs.

# Install changesets in root
pnpm add -Wd @changesets/cli
pnpm changeset init

Typical Release Flow​

  1. Add a Changeset: When you make a change, run pnpm changeset. It will ask which packages changed and what type of bump (patch, minor, major) is needed.
  2. Commit: Commit the generated .changeset/*.md file.
  3. Version: When ready to release, run pnpm changeset version. This will:
    • Bump versions in package.json files.
    • Update CHANGELOG.md for each package.
    • Delete the changeset files.
  4. Publish: Run pnpm publish -r.

Git Versioning Best Practices​

SemVer​

Always follow Semantic Versioning:

  • MAJOR.MINOR.PATCH
  • MAJOR: Breaking changes.
  • MINOR: New features (backward compatible).
  • PATCH: Bug fixes (backward compatibile).

Git Tagging​

Use Git tags to mark release points:

# Tag a release
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Conventional Commits​

Use Conventional Commits to automate versioning:

  • feat: ... -> Minor bump
  • fix: ... -> Patch bump
  • feat!: ... -> Major bump (breaking change)

Standalone Example: Manual Release Script​

If you prefer a manual approach without extra tools, you can use a simple script to bump and tag:

#!/bin/bash
# Simple release script example

VERSION=$1

if [ -z "$VERSION" ]; then
  echo "Usage: ./release.sh 1.0.0"
  exit 1
fi

# 1. Update versions (manual or via pnpm)
pnpm -r exec npm version $VERSION --no-git-tag-version

# 2. Commit and Tag
git add .
git commit -m "chore: release v$VERSION"
git tag -a "v$VERSION" -m "version $VERSION"

echo "Release v$VERSION ready. Push with: git push origin main --tags"