feat: implement modular capability system with automatic discovery
- Move release management to capabilities/release-management/ with complete Makefile - Create automatic capability discovery system in scripts/capability_discovery.mk - Add capability-manager subagent for managing modular architecture - Implement target delegation system enabling capability-name-target patterns - Create Makefiles for markitect-content, markitect-utils, and issue-facade capabilities - Remove legacy release management code and documentation from main project - Update main Makefile to use capability discovery and delegation - Add comprehensive capability status, help, and management targets The capability system provides: - Automatic discovery of capabilities with Makefiles - Clean target delegation without conflicts - Modular architecture following established patterns - Comprehensive help and status reporting - Zero-conflict capability integration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
229
capabilities/release-management/docs/package_publishing.md
Normal file
229
capabilities/release-management/docs/package_publishing.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user