Files

tegwick b7e11461f4 chore: rename markitect_project to markitect-main across project

Finishes the in-progress rename so docs, configs, tests, and capability
manifests all reference the current repo name consistently. Fixes two
tests (test_roundtrip_consolidated.py, test_issue_140_roundtrip_simplified.py)
whose hardcoded cwd paths would have broken under the renamed directory.

Archival content under history/, reports/, and roadmap/eat-the-frog/, plus
derived artifacts (.venv_old/, node_modules/, asset_registry.json) are
intentionally left untouched.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-04-21 01:57:35 +02:00

5.1 KiB

Raw Blame History

Package Publishing Guide

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

Prerequisites

Gitea API Token: Set the GITEA_API_TOKEN environment variable with your Gitea API token
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-main
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

5.1 KiB Raw Blame History