wehub-resource-sync
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 |