mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
Add comprehensive PyPI publishing infrastructure
## 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>
This commit is contained in:
NomenAK
293
PUBLISHING.md
Normal file
293
PUBLISHING.md
Normal file
@@ -0,0 +1,293 @@
|
||||
# SuperClaude PyPI Publishing Guide
|
||||
|
||||
This guide covers the complete process for publishing SuperClaude to PyPI (Python Package Index).
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Validate Project Readiness
|
||||
```bash
|
||||
python3 scripts/validate_pypi_ready.py
|
||||
```
|
||||
|
||||
### 2. Test Upload to TestPyPI
|
||||
```bash
|
||||
./scripts/publish.sh test
|
||||
```
|
||||
|
||||
### 3. Test Installation
|
||||
```bash
|
||||
./scripts/publish.sh test-install
|
||||
```
|
||||
|
||||
### 4. Production Upload
|
||||
```bash
|
||||
./scripts/publish.sh prod
|
||||
```
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
### 1. PyPI Accounts
|
||||
- **Production PyPI**: https://pypi.org/account/register/
|
||||
- **TestPyPI**: https://test.pypi.org/account/register/
|
||||
|
||||
### 2. API Tokens
|
||||
Generate tokens with appropriate permissions:
|
||||
- **PyPI**: https://pypi.org/manage/account/ → API tokens
|
||||
- **TestPyPI**: https://test.pypi.org/manage/account/ → API tokens
|
||||
|
||||
### 3. Local Configuration
|
||||
Create `~/.pypirc`:
|
||||
```ini
|
||||
[pypi]
|
||||
username = __token__
|
||||
password = pypi-[your-production-token-here]
|
||||
|
||||
[testpypi]
|
||||
repository = https://test.pypi.org/legacy/
|
||||
username = __token__
|
||||
password = pypi-[your-test-token-here]
|
||||
```
|
||||
|
||||
### 4. Install Required Tools
|
||||
```bash
|
||||
pip install --upgrade build twine toml
|
||||
```
|
||||
|
||||
## 📦 Package Information
|
||||
|
||||
- **Package Name**: `SuperClaude`
|
||||
- **Current Version**: `4.0.0b1` (beta release)
|
||||
- **Entry Points**:
|
||||
- `SuperClaude` → `SuperClaude.__main__:main`
|
||||
- `superclaude` → `SuperClaude.__main__:main`
|
||||
|
||||
## 🔧 Available Scripts
|
||||
|
||||
### Shell Script (Recommended)
|
||||
```bash
|
||||
# Test publishing
|
||||
./scripts/publish.sh test
|
||||
|
||||
# Test installation from TestPyPI
|
||||
./scripts/publish.sh test-install
|
||||
|
||||
# Production publishing
|
||||
./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
|
||||
```
|
||||
|
||||
### Python Script (Advanced)
|
||||
```bash
|
||||
# Basic TestPyPI upload
|
||||
python3 scripts/build_and_upload.py --testpypi
|
||||
|
||||
# TestPyPI with installation test
|
||||
python3 scripts/build_and_upload.py --testpypi --test-install
|
||||
|
||||
# Production upload
|
||||
python3 scripts/build_and_upload.py
|
||||
|
||||
# Skip validation (faster)
|
||||
python3 scripts/build_and_upload.py --skip-validation --testpypi
|
||||
|
||||
# Clean artifacts only
|
||||
python3 scripts/build_and_upload.py --clean
|
||||
```
|
||||
|
||||
### Validation Script
|
||||
```bash
|
||||
# Check if project is ready for publishing
|
||||
python3 scripts/validate_pypi_ready.py
|
||||
```
|
||||
|
||||
## 🤖 GitHub Actions Automation
|
||||
|
||||
The project includes automated publishing via GitHub Actions:
|
||||
|
||||
### Automatic Release Publishing
|
||||
1. Create a new release on GitHub
|
||||
2. GitHub Actions automatically builds and publishes to PyPI
|
||||
3. Package becomes available on PyPI within minutes
|
||||
|
||||
### Manual Publishing
|
||||
1. Go to GitHub Actions tab
|
||||
2. Select "Publish to PyPI" workflow
|
||||
3. Click "Run workflow"
|
||||
4. Choose target (testpypi or pypi)
|
||||
|
||||
### Required Secrets
|
||||
Set these in GitHub repository settings:
|
||||
- `PYPI_API_TOKEN`: Production PyPI token
|
||||
- `TEST_PYPI_API_TOKEN`: TestPyPI token
|
||||
|
||||
## 📈 Version Management
|
||||
|
||||
### Current Version: 4.0.0b1
|
||||
The project uses [semantic versioning](https://semver.org/) with beta notation:
|
||||
- `4.0.0b1` = Version 4.0.0, Beta 1
|
||||
- `4.0.0b2` = Version 4.0.0, Beta 2
|
||||
- `4.0.0` = Version 4.0.0, Stable Release
|
||||
|
||||
### Update Version Process
|
||||
1. Update version in:
|
||||
- `pyproject.toml`
|
||||
- `SuperClaude/__init__.py`
|
||||
- `SuperClaude/__main__.py`
|
||||
- `setup/__init__.py`
|
||||
|
||||
2. Validate consistency:
|
||||
```bash
|
||||
python3 scripts/validate_pypi_ready.py
|
||||
```
|
||||
|
||||
3. Commit and tag:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Bump version to X.Y.Z"
|
||||
git tag vX.Y.Z
|
||||
git push origin main --tags
|
||||
```
|
||||
|
||||
## 🔍 Package Structure
|
||||
|
||||
The package includes:
|
||||
```
|
||||
SuperClaude/
|
||||
├── SuperClaude/ # Main package
|
||||
│ ├── __init__.py # Package metadata
|
||||
│ ├── __main__.py # CLI entry point
|
||||
│ ├── Core/ # Framework core files
|
||||
│ ├── Commands/ # Command definitions
|
||||
│ ├── Agents/ # Agent specifications
|
||||
│ ├── Modes/ # Behavioral modes
|
||||
│ └── MCP/ # MCP server configs
|
||||
├── setup/ # Installation system
|
||||
├── scripts/ # Publishing scripts
|
||||
├── pyproject.toml # Package configuration
|
||||
├── README.md # Project documentation
|
||||
├── LICENSE # MIT license
|
||||
└── MANIFEST.in # Package manifest
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Local Testing
|
||||
```bash
|
||||
# Build package
|
||||
python3 -m build
|
||||
|
||||
# Check distribution
|
||||
python3 -m twine check dist/*
|
||||
|
||||
# Test local installation
|
||||
pip install dist/SuperClaude-4.0.0b1-py3-none-any.whl
|
||||
```
|
||||
|
||||
### TestPyPI Testing
|
||||
```bash
|
||||
# Upload to TestPyPI
|
||||
./scripts/publish.sh test
|
||||
|
||||
# Install from TestPyPI
|
||||
pip install --index-url https://test.pypi.org/simple/ \
|
||||
--extra-index-url https://pypi.org/simple/ \
|
||||
SuperClaude
|
||||
|
||||
# Test CLI
|
||||
SuperClaude --version
|
||||
```
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Version Already Exists
|
||||
PyPI doesn't allow re-uploading the same version. Increment version number:
|
||||
```bash
|
||||
# Current: 4.0.0b1
|
||||
# Next: 4.0.0b2 or 4.0.0
|
||||
```
|
||||
|
||||
#### Import Errors
|
||||
Check package structure and `__init__.py` files:
|
||||
```bash
|
||||
python3 scripts/validate_pypi_ready.py
|
||||
```
|
||||
|
||||
#### Upload Failures
|
||||
1. Check API tokens are correct
|
||||
2. Verify network connectivity
|
||||
3. Try TestPyPI first
|
||||
4. Check PyPI status page
|
||||
|
||||
#### Build Failures
|
||||
1. Ensure Python ≥3.8
|
||||
2. Update build tools: `pip install --upgrade build twine`
|
||||
3. Clean artifacts: `./scripts/publish.sh clean`
|
||||
|
||||
### Getting Help
|
||||
- PyPI Help: https://pypi.org/help/
|
||||
- Packaging Guide: https://packaging.python.org/
|
||||
- GitHub Issues: https://github.com/SuperClaude-Org/SuperClaude_Framework/issues
|
||||
|
||||
## 📊 Publication Checklist
|
||||
|
||||
Before publishing to production PyPI:
|
||||
|
||||
- [ ] All tests passing
|
||||
- [ ] Version number updated
|
||||
- [ ] Documentation updated
|
||||
- [ ] CHANGELOG.md updated
|
||||
- [ ] TestPyPI upload successful
|
||||
- [ ] TestPyPI installation test passed
|
||||
- [ ] GitHub release created (for automatic publishing)
|
||||
|
||||
## 🎯 Production Publishing
|
||||
|
||||
### Option 1: GitHub Release (Recommended)
|
||||
1. Push all changes to main branch
|
||||
2. Create new release on GitHub with tag `v4.0.0b1`
|
||||
3. GitHub Actions automatically publishes to PyPI
|
||||
|
||||
### Option 2: Manual Publishing
|
||||
```bash
|
||||
# Validate everything
|
||||
python3 scripts/validate_pypi_ready.py
|
||||
|
||||
# Test on TestPyPI first
|
||||
./scripts/publish.sh test
|
||||
./scripts/publish.sh test-install
|
||||
|
||||
# Publish to production
|
||||
./scripts/publish.sh prod
|
||||
```
|
||||
|
||||
## 🔐 Security Best Practices
|
||||
|
||||
- Store API tokens securely (use `~/.pypirc` or environment variables)
|
||||
- Never commit tokens to version control
|
||||
- Use minimal permission tokens
|
||||
- Regularly rotate API tokens
|
||||
- Use Trusted Publishing for GitHub Actions when possible
|
||||
|
||||
## 📝 Post-Publication
|
||||
|
||||
After successful publication:
|
||||
|
||||
1. **Update README badges** with new version
|
||||
2. **Announce release** on relevant channels
|
||||
3. **Monitor for issues** in GitHub Issues
|
||||
4. **Update documentation** if needed
|
||||
5. **Plan next release** based on feedback
|
||||
|
||||
---
|
||||
|
||||
*For questions or issues with publishing, please open an issue on GitHub or contact the maintainers.*
|
||||
Reference in New Issue
Block a user