Add complete Gitea package publishing support
✨ Features: - GiteaPackageRegistry client for PyPI-compatible uploads - Enhanced release.py with upload/registry commands - New Makefile targets for Gitea publishing workflow - Comprehensive documentation with examples 📦 New Commands: - `release.py registry` - Show registry info & authentication - `release.py upload` - Upload packages to Gitea - `release.py publish --to-gitea` - Complete release + upload - `make release-publish-gitea VERSION=x.y.z` - One-command release 🔧 Infrastructure: - Automatic package detection (wheel + sdist) - Dry-run support for safe testing - Error handling and detailed feedback - Authentication validation 📚 Documentation: - PACKAGE_PUBLISHING.md with complete setup guide - Usage examples and troubleshooting 🚀 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
159
PACKAGE_PUBLISHING.md
Normal file
159
PACKAGE_PUBLISHING.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# Package Publishing to Gitea
|
||||
|
||||
This document explains how to publish MarkiTect packages to the Gitea package registry.
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Check Registry Status
|
||||
|
||||
```bash
|
||||
# Check registry configuration and authentication
|
||||
make release-registry
|
||||
# or
|
||||
python release.py registry
|
||||
```
|
||||
|
||||
### Build and Upload Packages
|
||||
|
||||
```bash
|
||||
# Complete release workflow with Gitea upload
|
||||
make release-publish-gitea VERSION=0.8.0
|
||||
# or
|
||||
python release.py publish --version 0.8.0 --to-gitea
|
||||
|
||||
# Upload existing packages
|
||||
make release-upload-gitea
|
||||
# or
|
||||
python release.py upload
|
||||
|
||||
# Dry run (test without uploading)
|
||||
python release.py upload --dry-run
|
||||
```
|
||||
|
||||
### Traditional Release (without Gitea)
|
||||
|
||||
```bash
|
||||
# Standard release without Gitea upload
|
||||
make release-publish VERSION=0.8.0
|
||||
python release.py 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
|
||||
Reference in New Issue
Block a user