coulomb/markitect-main
Archived
2
0
Fork 0
Code Issues 135 Pull Requests Actions Projects 12 Releases 1 Wiki Activity

feat: implement modular capability system with automatic discovery

Browse Source 
- Move release management to capabilities/release-management/ with complete Makefile
- Create automatic capability discovery system in scripts/capability_discovery.mk
- Add capability-manager subagent for managing modular architecture
- Implement target delegation system enabling capability-name-target patterns
- Create Makefiles for markitect-content, markitect-utils, and issue-facade capabilities
- Remove legacy release management code and documentation from main project
- Update main Makefile to use capability discovery and delegation
- Add comprehensive capability status, help, and management targets

The capability system provides:
- Automatic discovery of capabilities with Makefiles
- Clean target delegation without conflicts
- Modular architecture following established patterns
- Comprehensive help and status reporting
- Zero-conflict capability integration

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2025-11-09 01:29:15 +01:00
parent d505c15d40
commit d0ffdc057c
38 changed files with 3978 additions and 1361 deletions
Download Patch File Download Diff File Expand all files Collapse all files

398
capabilities/release-management/MIGRATION_PLAN.md Normal file
View File

@@ -0,0 +1,398 @@
# 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_project/
├── 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.