# 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**:
```json
{
  "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**:
```json
{
  "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**:
```bash
# 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:

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

### Production

Pin versions for releases:

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

---

## Release Process

### 1. Version Bump

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

### 2. Build Package

```bash
pnpm build
```

### 3. Publish

```bash
pnpm publish --registry=<registry-url>
```

### 4. Update Projects

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

---

## Changelog

### Format

```markdown
# 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:

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

```bash
# 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

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

### Project Using Shared Package

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

---

**Last Updated**: 2025-01-27