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

# 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