markitect-main/capabilities/release-management/docs/package_publishing.md

# Package Publishing Guide

This guide covers building, publishing, and distributing MarkiTect packages using our Gitea package registry and setuptools-scm version management.

## Prerequisites

1. **Gitea API Token**: Set the `GITEA_API_TOKEN` environment variable with your Gitea API token
2. **Repository Access**: The token must have write access to the repository's package registry

## Quick Setup

```bash
# Set your Gitea API token
export GITEA_API_TOKEN="your_gitea_api_token_here"

# Or add it to your shell profile
echo "export GITEA_API_TOKEN=your_token" >> ~/.bashrc
```

## Package Building

### Quick Package Building

```bash
# Build distribution packages (recommended)
make package

# This will:
# 1. Show current version (setuptools-scm)
# 2. Clean previous builds
# 3. Build both wheel and source distribution
# 4. Show package details
```

### Manual Building

```bash
# Standard build
make build

# Using release script
make release-build
python release.py build

# Manual Python build
python -m build
```

## Publishing Workflow

### Complete Release + Publishing

```bash
# 🚀 ONE-COMMAND RELEASE (recommended)
make release-publish-gitea VERSION=0.8.0

# This complete workflow:
# 1. Creates git tag v0.8.0
# 2. Builds packages (setuptools-scm uses tag for version 0.8.0)
# 3. Uploads both wheel and source distribution to Gitea
```

### Step-by-Step Release

```bash
# 1. Check current status
make release-status

# 2. Validate release readiness
make release-validate

# 3. Create git tag
make release-tag VERSION=0.8.0

# 4. Build packages (version auto-detected from tag)
make release-build

# 5. Upload to Gitea registry
make release-upload-gitea
```

### Development Package Testing

```bash
# Build current development version
make package

# Upload development packages for testing
python release.py upload --dry-run  # Test first
python release.py upload            # Upload development version
```

## Registry Management

### Check Registry Status

```bash
# Comprehensive registry information
make release-registry

# Shows:
# - Authentication status
# - Registry URLs
# - Existing packages
# - Configuration details
```

### Upload Existing Packages

```bash
# Upload packages in dist/ folder
make release-upload-gitea

# With dry-run testing
python release.py upload --dry-run
python release.py upload
```

### Traditional Release (Git tags only)

```bash
# Standard release without Gitea upload
make release-publish VERSION=0.8.0
```

## Available Commands

### Makefile Targets

- `make release-registry` - Show Gitea package registry information
- `make release-upload-gitea` - Upload existing packages to Gitea
- `make release-publish-gitea VERSION=x.y.z` - Complete release + Gitea upload

### Python Script Commands

- `python release.py registry` - Show registry information
- `python release.py upload` - Upload packages to Gitea
- `python release.py upload --dry-run` - Test upload without uploading
- `python release.py publish --version x.y.z --to-gitea` - Release with Gitea upload

## Registry Information

- **Gitea URL**: http://92.205.130.254:32166
- **Repository**: coulomb/markitect_project
- **PyPI Registry URL**: http://92.205.130.254:32166/api/packages/coulomb/pypi
- **Package List URL**: http://92.205.130.254:32166/api/v1/packages/coulomb

## Installing from Gitea Registry

Once packages are published, users can install them using:

```bash
# Install from Gitea registry
pip install markitect --extra-index-url http://92.205.130.254:32166/api/packages/coulomb/pypi/simple/

# Or configure pip permanently
mkdir -p ~/.pip
cat >> ~/.pip/pip.conf << EOF
[global]
extra-index-url = http://92.205.130.254:32166/api/packages/coulomb/pypi/simple/
EOF
```

## Features

### Automatic Package Detection

The system automatically detects and uploads:
- **Wheel files** (`.whl`) - Binary distributions
- **Source distributions** (`.tar.gz`) - Source code packages

### Version Management with setuptools-scm

Versions are automatically determined by git tags:
- `v0.8.0` tag → `0.8.0` package version
- Development commits → `0.8.1.dev3+gcommithash` versions

### Error Handling

The system provides detailed error messages for:
- Missing authentication tokens
- Network connectivity issues
- Package upload failures
- Invalid package formats

## Troubleshooting

### Authentication Issues

```bash
# Check if token is set
echo $GITEA_API_TOKEN

# Test authentication
python release.py registry
```

### Upload Failures

```bash
# Test with dry run first
python release.py upload --dry-run

# Check package files exist
ls -la dist/

# Rebuild packages if needed
make release-build
```

### Network Issues

- Ensure Gitea server is accessible: `ping 92.205.130.254`
- Check firewall and proxy settings
- Verify Gitea is running on port 32166

## Development

The package registry functionality is implemented in:
- `gitea/package_registry.py` - Main package registry client
- `release.py` - Release script with Gitea integration
- `Makefile` - Convenient targets for package management

## Security Notes

- Never commit API tokens to version control
- Use environment variables or secure credential storage
- Tokens should have minimal required permissions
- Rotate tokens regularly for security