Initial commit: add .gitignore and README

VERSIONING_STRATEGY.md

@@ -0,0 +1,320 @@
+# 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
+