docs/VERSIONING_STRATEGY.md

Unified Versioning Strategy

Date: 2025-01-27 Purpose: Strategy for unified versioning across monorepos and shared packages Status: Complete

---

Overview

This document outlines the versioning strategy for shared packages, monorepos, and projects in the integrated workspace.

---

Versioning Approaches

Option 1: Independent Versioning (Recommended)

Strategy: Each package/project has its own version

Pros:

• Clear version history per package
• Independent release cycles
• Easier to track changes

Cons:

• More version management
• Potential compatibility issues

Usage:

{
  "name": "@workspace/shared-types",
  "version": "1.2.3"
}

Option 2: Unified Versioning

Strategy: Single version for entire monorepo

Pros:

• Simpler version management
• Guaranteed compatibility
• Easier coordination

Cons:

• All packages version together
• Less flexibility

Usage:

{
  "version": "1.2.3"  // Same for all packages
}

Recommendation: Use independent versioning for flexibility.

---

Semantic Versioning

Version Format: MAJOR.MINOR.PATCH

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

Examples

• 1.0.0 → 1.0.1 (patch: bug fix)
• 1.0.1 → 1.1.0 (minor: new feature)
• 1.1.0 → 2.0.0 (major: breaking change)

---

Versioning Rules

Shared Packages

Initial Release: 1.0.0

Version Bumps:

• Patch: Bug fixes, documentation
• Minor: New features, backward compatible
• Major: Breaking changes

Example:

# Patch release
pnpm version patch  # 1.0.0 → 1.0.1

# Minor release
pnpm version minor  # 1.0.1 → 1.1.0

# Major release
pnpm version major  # 1.1.0 → 2.0.0

Monorepos

Strategy: Track version of main package or use unified version

DBIS Monorepo:

• Track dbis_core version as main
• Other packages version independently

Defi-Mix-Tooling:

• Each submodule versions independently
• Monorepo tracks latest submodule versions

---

Workspace Protocol

Development

Use workspace:* for shared packages during development:

{
  "dependencies": {
    "@workspace/shared-types": "workspace:*"
  }
}

Production

Pin versions for releases:

{
  "dependencies": {
    "@workspace/shared-types": "^1.2.0"
  }
}

---

Release Process

1. Version Bump

cd workspace-shared/packages/shared-types
pnpm version patch  # or minor, major

2. Build Package

pnpm build

3. Publish

pnpm publish --registry=<registry-url>

4. Update Projects

cd project-directory
pnpm update @workspace/shared-types

---

Changelog

Format

# Changelog

## [1.2.0] - 2025-01-27

### Added
- New utility functions
- Additional type definitions

### Changed
- Improved error handling

### Fixed
- Bug fix in validation

Maintenance

• Update changelog with each release
• Document breaking changes
• Include migration guides for major versions

---

Version Tags

Git Tags

Tag releases in git:

git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

Tag Format

• v1.2.3 for releases
• v1.2.3-beta.1 for pre-releases
• v1.2.3-rc.1 for release candidates

---

Compatibility

Breaking Changes

When to bump MAJOR:

• Removed public APIs
• Changed function signatures
• Changed data structures
• Removed dependencies

Migration:

• Document breaking changes
• Provide migration guide
• Support both versions during transition

Backward Compatibility

Maintain for:

• At least 2 minor versions
• 6 months minimum
• Until migration complete

---

Automation

Version Bumping

Use tools for automated versioning:

• Changesets: Track changes and bump versions
• Semantic Release: Automated versioning from commits
• Lerna: Monorepo version management

Recommended: Changesets

# Add changeset
pnpm changeset

# Version packages
pnpm changeset version

# Publish
pnpm changeset publish

---

Best Practices

Version Management

• Use semantic versioning consistently
• Document all breaking changes
• Maintain changelog
• Tag releases in git

Dependency Management

• Pin versions for production
• Use workspace:* for development
• Regular dependency updates
• Security patch priority

Release Coordination

• Coordinate major releases
• Test compatibility
• Communicate changes
• Provide migration guides

---

Examples

Shared Package Versioning

{
  "name": "@workspace/shared-types",
  "version": "1.2.3",
  "dependencies": {
    // No dependencies
  }
}

Project Using Shared Package

{
  "name": "my-project",
  "version": "2.1.0",
  "dependencies": {
    "@workspace/shared-types": "^1.2.0"
  }
}

---

Last Updated: 2025-01-27