321 lines
4.8 KiB
Markdown
321 lines
4.8 KiB
Markdown
# 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
|
|
|