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

• Create directory structure
• Create README.md with comprehensive documentation
• Create pyproject.toml with full configuration
• Create main __init__.py with API exports
• 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:

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

   # Add at top of Makefile
   include capabilities/release-management/release.mk
   

2. Update existing targets to use capability:

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

   [project.dependencies]
   release-management = {path = "capabilities/release-management", develop = true}
   

2. Keep setuptools-scm configuration:

   [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:

• release.py (moved to capability CLI)
• gitea/ directory (moved to capability registries)
• VERSION_MANAGEMENT.md (moved to capability docs)
• 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

# 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

# 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.