feat: implement modular capability system with automatic discovery
- 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:
334
capabilities/release-management/README.md
Normal file
334
capabilities/release-management/README.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# Release Management Capability
|
||||
|
||||
A self-contained capability for version management, package building, and release publication with Git and package registry integration.
|
||||
|
||||
## Overview
|
||||
|
||||
The release-management capability provides comprehensive release automation for Python projects using setuptools-scm for version management and supporting multiple publication targets including Gitea package registries.
|
||||
|
||||
## Features
|
||||
|
||||
- **Automatic Version Management**: Git tag-based versioning with setuptools-scm
|
||||
- **Package Building**: Wheel and source distribution generation
|
||||
- **Release Automation**: Complete release workflow from validation to publication
|
||||
- **Multi-Platform Publishing**: Support for Gitea, GitHub, and other package registries
|
||||
- **Fallback Publishing**: Release assets when package registries unavailable
|
||||
- **CLI Integration**: Command-line tools for release management
|
||||
- **Makefile Integration**: Convenient targets for common release tasks
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
#### `ReleaseManager`
|
||||
Main orchestrator for release workflows, handling:
|
||||
- Release state validation
|
||||
- Git tag creation and management
|
||||
- Package building coordination
|
||||
- Publication orchestration
|
||||
|
||||
#### `PackageBuilder`
|
||||
Responsible for package generation:
|
||||
- setuptools-scm integration
|
||||
- Wheel and source distribution building
|
||||
- Build artifact management
|
||||
|
||||
#### `PublishManager`
|
||||
Handles package publication:
|
||||
- Multiple registry support (Gitea, PyPI, etc.)
|
||||
- Fallback mechanisms (release assets)
|
||||
- Upload progress tracking
|
||||
|
||||
#### `GitManager`
|
||||
Git operations for releases:
|
||||
- Tag creation and validation
|
||||
- Repository state checking
|
||||
- Branch and commit management
|
||||
|
||||
### Package Registry Support
|
||||
|
||||
#### `GiteaRegistry`
|
||||
Gitea-specific package registry client:
|
||||
- PyPI-compatible registry uploads
|
||||
- Release asset fallback
|
||||
- Authentication handling
|
||||
|
||||
#### `RegistryFactory`
|
||||
Factory for creating registry clients:
|
||||
- Auto-detection of registry types
|
||||
- Configuration management
|
||||
- Extensible for new registries
|
||||
|
||||
## API Reference
|
||||
|
||||
### Core Classes
|
||||
|
||||
#### `ReleaseManager`
|
||||
```python
|
||||
from release_management import ReleaseManager
|
||||
|
||||
manager = ReleaseManager()
|
||||
|
||||
# Validate release readiness
|
||||
is_valid, issues = manager.validate_release_state()
|
||||
|
||||
# Create complete release
|
||||
success = manager.publish_release("0.8.0")
|
||||
|
||||
# Publish with specific registry
|
||||
success = manager.publish_with_registry("0.8.0", registry_type="gitea")
|
||||
```
|
||||
|
||||
#### `PackageBuilder`
|
||||
```python
|
||||
from release_management import PackageBuilder
|
||||
|
||||
builder = PackageBuilder()
|
||||
|
||||
# Build packages
|
||||
builder.build_packages()
|
||||
|
||||
# Get current version
|
||||
version = builder.get_current_version()
|
||||
|
||||
# Clean build artifacts
|
||||
builder.clean_build()
|
||||
```
|
||||
|
||||
#### `PublishManager`
|
||||
```python
|
||||
from release_management import PublishManager
|
||||
|
||||
publisher = PublishManager()
|
||||
|
||||
# Publish to registry
|
||||
success = publisher.publish_packages("gitea", dry_run=True)
|
||||
|
||||
# Upload specific files
|
||||
success = publisher.upload_file("dist/package.whl", "gitea")
|
||||
```
|
||||
|
||||
### CLI Commands
|
||||
|
||||
#### `release`
|
||||
Main release command with subcommands:
|
||||
|
||||
```bash
|
||||
# Show release status
|
||||
release status
|
||||
|
||||
# Validate release readiness
|
||||
release validate
|
||||
|
||||
# Create git tag
|
||||
release tag --version 0.8.0
|
||||
|
||||
# Build packages
|
||||
release build
|
||||
|
||||
# Complete release workflow
|
||||
release publish --version 0.8.0
|
||||
|
||||
# Publish to specific registry
|
||||
release publish --version 0.8.0 --registry gitea
|
||||
|
||||
# Upload existing packages
|
||||
release upload --registry gitea
|
||||
|
||||
# Show registry information
|
||||
release registry-info --registry gitea
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
#### Release Configuration
|
||||
Configure release behavior in `pyproject.toml`:
|
||||
|
||||
```toml
|
||||
[tool.release-management]
|
||||
# Default registry for publishing
|
||||
default_registry = "gitea"
|
||||
|
||||
# Validation requirements
|
||||
require_clean_tree = true
|
||||
require_main_branch = true
|
||||
|
||||
# Package building
|
||||
build_wheel = true
|
||||
build_sdist = true
|
||||
clean_before_build = true
|
||||
|
||||
# Registry configurations
|
||||
[tool.release-management.registries.gitea]
|
||||
url = "http://92.205.130.254:32166"
|
||||
owner = "coulomb"
|
||||
repo = "markitect_project"
|
||||
auth_token_env = "GITEA_API_TOKEN"
|
||||
|
||||
[tool.release-management.registries.pypi]
|
||||
url = "https://upload.pypi.org/legacy/"
|
||||
auth_token_env = "PYPI_TOKEN"
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
Install as an editable dependency:
|
||||
|
||||
```bash
|
||||
pip install -e capabilities/release-management/
|
||||
```
|
||||
|
||||
Or with development dependencies:
|
||||
|
||||
```bash
|
||||
pip install -e "capabilities/release-management/[dev]"
|
||||
```
|
||||
|
||||
## Development Setup
|
||||
|
||||
```bash
|
||||
cd capabilities/release-management/
|
||||
pip install -e ".[dev]"
|
||||
pytest tests/
|
||||
```
|
||||
|
||||
## Integration with Main Project
|
||||
|
||||
The main project integrates with this capability through:
|
||||
|
||||
### Makefile Integration
|
||||
```makefile
|
||||
# Include release management targets
|
||||
include capabilities/release-management/release.mk
|
||||
|
||||
# Or call capability directly
|
||||
release-status:
|
||||
release status
|
||||
|
||||
release-publish:
|
||||
release publish --version $(VERSION)
|
||||
```
|
||||
|
||||
### Setup Configuration
|
||||
In main project's `pyproject.toml`:
|
||||
|
||||
```toml
|
||||
[tool.setuptools_scm]
|
||||
write_to = "markitect/_version.py"
|
||||
|
||||
[tool.release-management]
|
||||
default_registry = "gitea"
|
||||
```
|
||||
|
||||
## Migration Plan
|
||||
|
||||
This capability consolidates the following existing components:
|
||||
|
||||
### Files to Move
|
||||
1. **`release.py`** → `src/release_management/cli/main.py`
|
||||
2. **`gitea/`** directory → `src/release_management/registries/gitea/`
|
||||
3. **VERSION_MANAGEMENT.md** → `docs/version_management.md`
|
||||
4. **PACKAGE_PUBLISHING.md** → `docs/package_publishing.md`
|
||||
5. **Makefile release targets** → `release.mk`
|
||||
|
||||
### New Structure
|
||||
```
|
||||
capabilities/release-management/
|
||||
├── README.md
|
||||
├── pyproject.toml
|
||||
├── release.mk # Makefile integration
|
||||
├── src/release_management/
|
||||
│ ├── __init__.py # Main API exports
|
||||
│ ├── 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
|
||||
│ │ ├── factory.py # RegistryFactory
|
||||
│ │ ├── base.py # Registry interface
|
||||
│ │ ├── gitea/
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── registry.py # GiteaRegistry
|
||||
│ │ │ ├── config.py # GiteaConfig
|
||||
│ │ │ └── exceptions.py # GiteaError
|
||||
│ │ └── pypi/
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── registry.py # PyPIRegistry
|
||||
│ ├── cli/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── main.py # Main CLI entry point
|
||||
│ │ ├── commands.py # CLI command implementations
|
||||
│ │ └── utils.py # CLI utilities
|
||||
│ └── utils/
|
||||
│ ├── __init__.py
|
||||
│ ├── version.py # Version management utilities
|
||||
│ └── validation.py # Release validation utilities
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ ├── test_manager.py
|
||||
│ ├── test_builder.py
|
||||
│ ├── test_publisher.py
|
||||
│ ├── test_git_manager.py
|
||||
│ ├── test_gitea_registry.py
|
||||
│ └── fixtures/
|
||||
│ └── sample_packages/
|
||||
├── docs/
|
||||
│ ├── version_management.md
|
||||
│ ├── package_publishing.md
|
||||
│ ├── api_reference.md
|
||||
│ └── examples/
|
||||
└── examples/
|
||||
├── basic_release.py
|
||||
├── custom_registry.py
|
||||
└── ci_integration.py
|
||||
```
|
||||
|
||||
## Benefits of Capability Structure
|
||||
|
||||
### Modularity
|
||||
- **Self-contained**: Independent testing and development
|
||||
- **Reusable**: Can be used in other projects
|
||||
- **Focused**: Single responsibility for release management
|
||||
|
||||
### Maintainability
|
||||
- **Clear boundaries**: Well-defined API surface
|
||||
- **Extensible**: Easy to add new registries or features
|
||||
- **Testable**: Comprehensive test suite in isolation
|
||||
|
||||
### Integration
|
||||
- **CLI integration**: Direct command-line access
|
||||
- **Makefile integration**: Convenient targets for workflows
|
||||
- **Configuration**: Centralized in pyproject.toml
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Core Dependencies
|
||||
- `click>=8.0.0` - CLI framework
|
||||
- `requests>=2.25.0` - HTTP client for registries
|
||||
- `setuptools-scm>=8.0.0` - Version management
|
||||
- `build>=0.8.0` - Package building
|
||||
- `packaging>=21.0` - Version parsing and validation
|
||||
|
||||
### Development Dependencies
|
||||
- `pytest>=7.0.0` - Testing framework
|
||||
- `pytest-cov>=4.0.0` - Coverage reporting
|
||||
- `responses>=0.20.0` - HTTP mocking for tests
|
||||
- `black>=22.0.0` - Code formatting
|
||||
- `flake8>=5.0.0` - Code linting
|
||||
- `mypy>=1.0.0` - Type checking
|
||||
|
||||
## Compliance
|
||||
|
||||
This capability follows the ComposableRepositoryParadigm:
|
||||
- ✅ Src layout (PEP 660 compliant)
|
||||
- ✅ Unidirectional dependencies
|
||||
- ✅ Self-contained with own tests
|
||||
- ✅ Independent configuration
|
||||
- ✅ Clean API boundaries
|
||||
- ✅ Type safety with mypy
|
||||
- ✅ Comprehensive documentation
|
||||
Reference in New Issue
Block a user