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

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

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

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:

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

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

pip install -e capabilities/release-management/

Or with development dependencies:

pip install -e "capabilities/release-management/[dev]"

Development Setup

cd capabilities/release-management/
pip install -e ".[dev]"
pytest tests/

Integration with Main Project

The main project integrates with this capability through:

Makefile Integration

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

[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