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

# 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

# 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

# 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

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

# 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

# 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

# Comprehensive registry information
make release-registry

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

Upload Existing Packages

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

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

# 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

# Check if token is set
echo $GITEA_API_TOKEN

# Test authentication
python release.py registry

Upload Failures

# 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