mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-26 22:26:20 +00:00
e8afb94163
## Version Management & Consistency - Update to version 4.0.0b1 (proper beta versioning for PyPI) - Add __version__ attribute to SuperClaude/__init__.py - Ensure version consistency across pyproject.toml, __main__.py, setup/__init__.py ## Enhanced Package Configuration - Improve pyproject.toml with comprehensive PyPI classifiers - Add proper license specification and enhanced metadata - Configure package discovery with inclusion/exclusion patterns - Add development and test dependencies ## Publishing Scripts & Tools - scripts/build_and_upload.py: Advanced Python script for building and uploading - scripts/publish.sh: User-friendly shell wrapper for common operations - scripts/validate_pypi_ready.py: Comprehensive validation and readiness checker - All scripts executable with proper error handling and validation ## GitHub Actions Automation - .github/workflows/publish-pypi.yml: Complete CI/CD pipeline - Automatic publishing on GitHub releases - Manual workflow dispatch for TestPyPI uploads - Package validation and installation testing ## Documentation & Security - PUBLISHING.md: Comprehensive PyPI publishing guide - scripts/README.md: Detailed script usage documentation - .env.example: Environment variable template - Secure token handling with both .pypirc and environment variables ## Features ✅ Version consistency validation across all files ✅ Comprehensive PyPI metadata and classifiers ✅ Multi-environment publishing (TestPyPI + PyPI) ✅ Automated GitHub Actions workflow ✅ Security best practices for API token handling ✅ Complete documentation and troubleshooting guides ✅ Enterprise-grade validation and error handling The SuperClaude Framework is now fully prepared for PyPI publication with professional-grade automation, validation, and documentation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
138 lines
3.4 KiB
Markdown
138 lines
3.4 KiB
Markdown
# SuperClaude PyPI Publishing Scripts
|
|
|
|
This directory contains scripts for building and publishing SuperClaude to PyPI.
|
|
|
|
## Scripts
|
|
|
|
### `publish.sh` - Main Publishing Script
|
|
Easy-to-use shell script for common publishing tasks:
|
|
|
|
```bash
|
|
# Test upload to TestPyPI
|
|
./scripts/publish.sh test
|
|
|
|
# Test installation from TestPyPI
|
|
./scripts/publish.sh test-install
|
|
|
|
# Production upload to PyPI
|
|
./scripts/publish.sh prod
|
|
|
|
# Build package only
|
|
./scripts/publish.sh build
|
|
|
|
# Clean build artifacts
|
|
./scripts/publish.sh clean
|
|
|
|
# Validate project structure
|
|
./scripts/publish.sh check
|
|
```
|
|
|
|
### `build_and_upload.py` - Advanced Build Script
|
|
Python script with detailed control over the build and upload process:
|
|
|
|
```bash
|
|
# Build and upload to TestPyPI
|
|
python scripts/build_and_upload.py --testpypi
|
|
|
|
# Test installation from TestPyPI
|
|
python scripts/build_and_upload.py --testpypi --test-install
|
|
|
|
# Production upload (with confirmation)
|
|
python scripts/build_and_upload.py
|
|
|
|
# Skip validation (for faster builds)
|
|
python scripts/build_and_upload.py --skip-validation --testpypi
|
|
|
|
# Clean only
|
|
python scripts/build_and_upload.py --clean
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
1. **PyPI Account**: Register at https://pypi.org/account/register/
|
|
2. **API Tokens**: Generate tokens at https://pypi.org/manage/account/
|
|
3. **Configuration**: Create `~/.pypirc`:
|
|
```ini
|
|
[pypi]
|
|
username = __token__
|
|
password = pypi-[your-production-token]
|
|
|
|
[testpypi]
|
|
repository = https://test.pypi.org/legacy/
|
|
username = __token__
|
|
password = pypi-[your-test-token]
|
|
```
|
|
|
|
## GitHub Actions
|
|
|
|
The `.github/workflows/publish-pypi.yml` workflow automates publishing:
|
|
|
|
- **Automatic**: Publishes to PyPI when a GitHub release is created
|
|
- **Manual**: Can be triggered manually for TestPyPI uploads
|
|
- **Validation**: Includes package validation and installation testing
|
|
|
|
### Required Secrets
|
|
|
|
Set these in your GitHub repository settings → Secrets and variables → Actions:
|
|
|
|
- `PYPI_API_TOKEN`: Production PyPI token
|
|
- `TEST_PYPI_API_TOKEN`: TestPyPI token
|
|
|
|
## Publishing Workflow
|
|
|
|
### 1. Development Release (TestPyPI)
|
|
```bash
|
|
# Test the build and upload process
|
|
./scripts/publish.sh test
|
|
|
|
# Verify the package installs correctly
|
|
./scripts/publish.sh test-install
|
|
```
|
|
|
|
### 2. Production Release (PyPI)
|
|
|
|
#### Option A: Manual
|
|
```bash
|
|
# Upload directly (requires confirmation)
|
|
./scripts/publish.sh prod
|
|
```
|
|
|
|
#### Option B: GitHub Release (Recommended)
|
|
1. Update version in code
|
|
2. Commit and push changes
|
|
3. Create a new release on GitHub
|
|
4. GitHub Actions will automatically build and publish
|
|
|
|
## Version Management
|
|
|
|
Before publishing, ensure version consistency across:
|
|
- `pyproject.toml`
|
|
- `SuperClaude/__init__.py`
|
|
- `SuperClaude/__main__.py`
|
|
- `setup/__init__.py`
|
|
|
|
The build script validates version consistency automatically.
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Failures
|
|
- Check Python version compatibility (≥3.8)
|
|
- Ensure all required files are present
|
|
- Validate `pyproject.toml` syntax
|
|
|
|
### Upload Failures
|
|
- Verify API tokens are correct
|
|
- Check if version already exists on PyPI
|
|
- Ensure package name is available
|
|
|
|
### Import Failures
|
|
- Check package structure (`__init__.py` files)
|
|
- Verify all dependencies are listed
|
|
- Test local installation first
|
|
|
|
## Security Notes
|
|
|
|
- Never commit API tokens to version control
|
|
- Use environment variables or `.pypirc` for credentials
|
|
- Tokens should have minimal required permissions
|
|
- Consider using Trusted Publishing for GitHub Actions |