markitect-main/capabilities/release-management/MIGRATION_PLAN.md

# Release Management Capability Migration Plan

This document outlines the step-by-step plan to migrate all version management, packaging, and release publication functionality from the main MarkiTect project into the `release-management` capability.

## 📋 Migration Overview

### Current State
Version management and release functionality is currently scattered across:
- `release.py` (main release script)
- `gitea/` directory (package registry client)
- `VERSION_MANAGEMENT.md` (documentation)
- `PACKAGE_PUBLISHING.md` (documentation)
- Makefile targets (release automation)
- setuptools-scm configuration in main `pyproject.toml`

### Target State
All release-related functionality consolidated into:
- `capabilities/release-management/` (self-contained capability)
- Main project depends on capability for release operations
- Makefile includes capability's release targets
- Clean separation of concerns

## 🚦 Migration Steps

### Phase 1: Create Capability Structure ✅ COMPLETED
- [x] Create directory structure
- [x] Create `README.md` with comprehensive documentation
- [x] Create `pyproject.toml` with full configuration
- [x] Create main `__init__.py` with API exports
- [x] Create `release.mk` for Makefile integration

### Phase 2: Move Core Files and Code

#### 2.1 Move Release Script
**Source:** `release.py` → **Target:** `src/release_management/cli/main.py`

**Steps:**
1. Copy `release.py` to `src/release_management/cli/main.py`
2. Refactor into proper CLI module structure
3. Extract core logic into separate modules:
   - `SimpleReleaseManager` → `src/release_management/core/manager.py`
   - Git operations → `src/release_management/git/manager.py`
   - Package building → `src/release_management/core/builder.py`
   - Publishing logic → `src/release_management/core/publisher.py`

**Refactoring Plan:**
```python
# Current: release.py (monolithic)
class SimpleReleaseManager:
    # All functionality in one class

# Target: Modular architecture
# src/release_management/core/manager.py
class ReleaseManager:
    def __init__(self):
        self.git_manager = GitManager()
        self.builder = PackageBuilder()
        self.publisher = PublishManager()

# src/release_management/git/manager.py
class GitManager:
    # Git-specific operations

# src/release_management/core/builder.py
class PackageBuilder:
    # Package building operations

# src/release_management/core/publisher.py
class PublishManager:
    # Publishing and upload operations
```

#### 2.2 Move Gitea Package Registry
**Source:** `gitea/` directory → **Target:** `src/release_management/registries/gitea/`

**File Mapping:**
```
gitea/config.py          → src/release_management/registries/gitea/config.py
gitea/exceptions.py      → src/release_management/registries/gitea/exceptions.py
gitea/package_registry.py → src/release_management/registries/gitea/registry.py
gitea/__init__.py        → src/release_management/registries/gitea/__init__.py
```

**Refactoring:**
1. Create base registry interface: `src/release_management/registries/base.py`
2. Create registry factory: `src/release_management/registries/factory.py`
3. Adapt GiteaPackageRegistry to implement base interface
4. Add PyPI registry implementation for future use

#### 2.3 Move Documentation
**Source:** Documentation files → **Target:** `docs/` directory

**File Mapping:**
```
VERSION_MANAGEMENT.md    → capabilities/release-management/docs/version_management.md
PACKAGE_PUBLISHING.md    → capabilities/release-management/docs/package_publishing.md
```

**Updates Required:**
1. Update paths and references in documentation
2. Add API reference documentation
3. Create examples directory with usage samples

### Phase 3: Update Main Project Integration

#### 3.1 Update Main Makefile
**Target:** `Makefile` in main project

**Changes:**
1. Include release management Makefile:
   ```makefile
   # Add at top of Makefile
   include capabilities/release-management/release.mk
   ```

2. Update existing targets to use capability:
   ```makefile
   # Old targets
   release-status:
       python release.py status

   # New targets (provided by release.mk)
   release-status:
       release status
   ```

3. Remove obsolete targets and replace with capability equivalents

#### 3.2 Update Main pyproject.toml
**Target:** `pyproject.toml` in main project

**Changes:**
1. Add release-management as dependency:
   ```toml
   [project.dependencies]
   release-management = {path = "capabilities/release-management", develop = true}
   ```

2. Keep setuptools-scm configuration:
   ```toml
   [tool.setuptools_scm]
   write_to = "markitect/_version.py"
   ```

3. Remove release-specific configuration (moved to capability)

#### 3.3 Update Main Project Structure
**Cleanup Tasks:**
1. Remove `release.py` from root
2. Remove `gitea/` directory
3. Move `VERSION_MANAGEMENT.md` and `PACKAGE_PUBLISHING.md` to capability
4. Update `.gitignore` if needed
5. Update documentation references

### Phase 4: Testing and Validation

#### 4.1 Create Capability Tests
**Target:** `capabilities/release-management/tests/`

**Test Structure:**
```
tests/
├── test_manager.py          # ReleaseManager tests
├── test_builder.py          # PackageBuilder tests
├── test_publisher.py        # PublishManager tests
├── test_git_manager.py      # GitManager tests
├── test_gitea_registry.py   # GiteaRegistry tests
├── test_cli.py              # CLI command tests
├── test_integration.py      # End-to-end tests
└── fixtures/
    └── sample_packages/     # Test package artifacts
```

**Test Coverage Goals:**
- Unit tests for all core classes
- Integration tests for registry interactions
- CLI command tests
- Mock-based tests for external dependencies
- Error handling and edge cases

#### 4.2 Validate Migration
**Verification Steps:**
1. Install capability: `pip install -e capabilities/release-management/`
2. Run capability tests: `cd capabilities/release-management && pytest`
3. Test CLI commands: `release --help`, `release status`
4. Test Makefile integration: `make release-status`
5. Perform test release workflow
6. Verify all existing functionality works

### Phase 5: Documentation and Examples

#### 5.1 Create Examples
**Target:** `capabilities/release-management/examples/`

**Example Scripts:**
- `basic_release.py` - Simple release workflow
- `custom_registry.py` - Adding new registry type
- `ci_integration.py` - CI/CD pipeline integration
- `configuration_examples.py` - Various configuration patterns

#### 5.2 Update Documentation
**Documentation Tasks:**
1. Update main project README to reference capability
2. Create API reference documentation
3. Add troubleshooting guide
4. Document configuration options
5. Provide migration guide for other projects

## 🎯 Detailed File Structure After Migration

```
markitect-main/
├── capabilities/
│   └── release-management/
│       ├── README.md                              ✅ CREATED
│       ├── pyproject.toml                         ✅ CREATED
│       ├── release.mk                            ✅ CREATED
│       ├── MIGRATION_PLAN.md                     ✅ CREATED
│       ├── src/release_management/
│       │   ├── __init__.py                       ✅ CREATED
│       │   ├── _version.py                       # Generated by setuptools-scm
│       │   ├── core/
│       │   │   ├── __init__.py
│       │   │   ├── manager.py                    # ReleaseManager class
│       │   │   ├── builder.py                    # PackageBuilder class
│       │   │   └── publisher.py                  # PublishManager class
│       │   ├── git/
│       │   │   ├── __init__.py
│       │   │   └── manager.py                    # GitManager class
│       │   ├── registries/
│       │   │   ├── __init__.py
│       │   │   ├── base.py                       # Registry interface
│       │   │   ├── factory.py                    # RegistryFactory
│       │   │   ├── gitea/
│       │   │   │   ├── __init__.py
│       │   │   │   ├── config.py                 # From gitea/config.py
│       │   │   │   ├── exceptions.py             # From gitea/exceptions.py
│       │   │   │   └── registry.py               # From gitea/package_registry.py
│       │   │   └── pypi/
│       │   │       ├── __init__.py
│       │   │       └── registry.py               # PyPI registry implementation
│       │   ├── cli/
│       │   │   ├── __init__.py
│       │   │   ├── main.py                       # From release.py
│       │   │   ├── commands.py                   # CLI command implementations
│       │   │   └── utils.py                      # CLI utilities
│       │   └── utils/
│       │       ├── __init__.py
│       │       ├── version.py                    # Version utilities
│       │       └── validation.py                # Release validation
│       ├── tests/
│       │   ├── __init__.py
│       │   ├── test_manager.py
│       │   ├── test_builder.py
│       │   ├── test_publisher.py
│       │   ├── test_git_manager.py
│       │   ├── test_gitea_registry.py
│       │   ├── test_cli.py
│       │   └── fixtures/
│       ├── docs/
│       │   ├── version_management.md             # From VERSION_MANAGEMENT.md
│       │   ├── package_publishing.md             # From PACKAGE_PUBLISHING.md
│       │   ├── api_reference.md
│       │   └── troubleshooting.md
│       └── examples/
│           ├── basic_release.py
│           ├── custom_registry.py
│           └── ci_integration.py
├── Makefile                                      # Updated to include release.mk
├── pyproject.toml                               # Updated with capability dependency
└── markitect/
    └── _version.py                              # Still generated by setuptools-scm
```

## 📦 Files to Remove After Migration

**Root Directory:**
- [x] `release.py` (moved to capability CLI)
- [x] `gitea/` directory (moved to capability registries)
- [x] `VERSION_MANAGEMENT.md` (moved to capability docs)
- [x] `PACKAGE_PUBLISHING.md` (moved to capability docs)

**Makefile Targets to Update:**
- Replace individual release targets with capability imports
- Keep legacy aliases for backward compatibility
- Update target documentation

## 🔧 API Design for Capability

### Main API Classes

```python
# Primary entry point
from release_management import ReleaseManager

manager = ReleaseManager()
success = manager.publish_release("1.0.0")

# Component access
from release_management import PackageBuilder, PublishManager, GitManager

builder = PackageBuilder()
builder.build_packages()

publisher = PublishManager()
publisher.upload_packages("gitea")

git = GitManager()
git.create_tag("v1.0.0")

# Registry access
from release_management import RegistryFactory

registry = RegistryFactory.create("gitea")
registry.upload_package("package.whl")
```

### CLI Interface

```bash
# Main commands
release status                    # Show release status
release validate                  # Validate release state
release tag --version 1.0.0      # Create git tag
release build                     # Build packages
release publish --version 1.0.0  # Complete release workflow
release upload --registry gitea   # Upload existing packages

# Registry management
release registry-info --registry gitea
release registry-list
```

## 🚀 Benefits After Migration

### For MarkiTect Project
1. **Cleaner main project**: Release logic separated from core functionality
2. **Better maintainability**: Clear module boundaries and responsibilities
3. **Easier testing**: Isolated testing of release functionality
4. **Reduced complexity**: Main project focuses on core features

### For Release Management Capability
1. **Reusability**: Can be used in other Python projects
2. **Independent development**: Own release cycle and versioning
3. **Comprehensive testing**: Full test coverage for release functionality
4. **Documentation**: Dedicated documentation and examples
5. **Extensibility**: Easy to add new registries and features

### For Users/Developers
1. **Consistent interface**: Same commands across all projects using capability
2. **Better documentation**: Comprehensive guides and API reference
3. **More features**: Enhanced functionality and registry support
4. **Easier contribution**: Clear structure for adding features

## 🎯 Success Criteria

Migration is considered successful when:
1. ✅ All existing release functionality works through capability
2. ✅ Main project Makefile targets work unchanged
3. ✅ CLI commands provide same functionality as current `release.py`
4. ✅ All tests pass for both capability and main project
5. ✅ Documentation is complete and accurate
6. ✅ Examples demonstrate capability usage
7. ✅ No regression in release workflow functionality

## 🔄 Rollback Plan

If migration issues arise:
1. **Keep backup**: Current files backed up before migration
2. **Incremental approach**: Migrate one component at a time
3. **Parallel operation**: Keep old and new systems running during transition
4. **Quick revert**: Ability to restore original structure if needed

**Rollback Steps:**
1. Remove capability dependency from main `pyproject.toml`
2. Restore backed up files (`release.py`, `gitea/`, docs)
3. Restore original Makefile targets
4. Remove capability directory
5. Test that original functionality works

## 📅 Migration Timeline

**Estimated Duration:** 1-2 weeks for complete migration

**Phase Breakdown:**
- **Phase 1 (Directory Structure):** ✅ COMPLETED
- **Phase 2 (Code Migration):** 2-3 days
- **Phase 3 (Integration):** 1-2 days
- **Phase 4 (Testing):** 2-3 days
- **Phase 5 (Documentation):** 1-2 days

**Critical Path:**
1. Code refactoring and migration
2. Testing and validation
3. Documentation updates
4. Final integration testing

This migration plan ensures a systematic, low-risk transition to the capability-based architecture while maintaining all existing functionality and improving the overall project structure.