mcp-name-cheap/PUBLISHING.md

# Publishing Guide

This document explains how to publish the MCP Name Cheap package to TestPyPI and PyPI.

## Prerequisites

1. **Install dependencies**:
   ```bash
   uv sync --extra dev
   ```

2. **Set up accounts**:
   - [TestPyPI account](https://test.pypi.org/account/register/)
   - [PyPI account](https://pypi.org/account/register/)

3. **Configure API tokens** (recommended over username/password):
   - Create API tokens in your PyPI account settings
   - Store in `~/.pypirc` or use environment variables

## Publishing Methods

### Method 1: Using the Publishing Script (Recommended)

The project includes a convenient publishing script:

```bash
# Publish to TestPyPI (safe testing)
python scripts/publish.py --target testpypi

# Publish to production PyPI
python scripts/publish.py --target pypi

# Skip tests (if already run)
python scripts/publish.py --target testpypi --skip-tests

# Skip building (if dist/ already exists)
python scripts/publish.py --target testpypi --skip-build
```

### Method 2: Manual Publishing

#### Step 1: Run Tests and Quality Checks
```bash
python run_tests.py --all
```

#### Step 2: Clean and Build
```bash
# Clean old builds
rm -rf dist/ build/

# Build package
python -m build
```

#### Step 3: Check Package
```bash
python -m twine check dist/*
```

#### Step 4: Publish to TestPyPI
```bash
python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
```

#### Step 5: Test Installation from TestPyPI
```bash
pip install -i https://test.pypi.org/simple/ mcp-namecheap
```

#### Step 6: Publish to PyPI (if TestPyPI works)
```bash
python -m twine upload dist/*
```

### Method 3: GitHub Actions (Automated)

#### For TestPyPI
```bash
# Manual workflow dispatch
gh workflow run publish.yml -f environment=testpypi
```

#### For PyPI
```bash
# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0
# This automatically triggers PyPI publishing
```

## Version Management

### Update Version
1. **Update version in `pyproject.toml`**:
   ```toml
   version = "1.0.1"
   ```

2. **Update version in `src/mcp_namecheap/__init__.py`**:
   ```python
   __version__ = "1.0.1"
   ```

3. **Commit changes**:
   ```bash
   git add .
   git commit -m "Bump version to 1.0.1"
   ```

4. **Tag release**:
   ```bash
   git tag v1.0.1
   git push origin main
   git push origin v1.0.1
   ```

### Semantic Versioning
Follow [Semantic Versioning](https://semver.org/):
- **MAJOR** (1.0.0): Breaking changes
- **MINOR** (0.1.0): New features, backwards compatible
- **PATCH** (0.0.1): Bug fixes, backwards compatible

## Testing Published Packages

### TestPyPI
```bash
# Install from TestPyPI
pip install -i https://test.pypi.org/simple/ mcp-namecheap

# Test basic functionality
python -c "import mcp_namecheap; print(mcp_namecheap.__version__)"
mcp-namecheap --help
```

### PyPI
```bash
# Install from PyPI
pip install mcp-namecheap

# Test installation
mcp-namecheap --help
```

## Configuration Files

### .pypirc (Optional)
Store credentials in `~/.pypirc`:
```ini
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-your-api-token-here

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-your-test-api-token-here
```

### Environment Variables
Alternatively, use environment variables:
```bash
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-your-api-token-here
```

## GitHub Repository Setup

### Secrets Configuration
Add these secrets to your GitHub repository:

1. Go to Settings → Secrets and variables → Actions
2. Add repository secrets:
   - `PYPI_API_TOKEN`: Your PyPI API token
   - `TEST_PYPI_API_TOKEN`: Your TestPyPI API token

### Environments
Configure environments for additional security:

1. Go to Settings → Environments
2. Create environments:
   - `testpypi`: For TestPyPI publishing
   - `pypi`: For PyPI publishing (with protection rules)

## Publishing Checklist

### Pre-Publishing
- [ ] All tests pass (`python run_tests.py --all`)
- [ ] Version number updated in both places
- [ ] CHANGELOG.md updated (if exists)
- [ ] Documentation updated
- [ ] Clean working directory (`git status`)

### TestPyPI Publishing
- [ ] Publish to TestPyPI
- [ ] Install from TestPyPI
- [ ] Test basic functionality
- [ ] Test MCP server functionality
- [ ] Verify documentation renders correctly

### PyPI Publishing
- [ ] TestPyPI version works correctly
- [ ] Create git tag for version
- [ ] Publish to PyPI
- [ ] Verify PyPI page looks correct
- [ ] Test installation from PyPI
- [ ] Update documentation with new version

## Troubleshooting

### Common Issues

#### "File already exists" error
- Version already published
- Update version number in `pyproject.toml`

#### "Invalid credentials" error
- Check API token
- Verify `.pypirc` configuration
- Try environment variables instead

#### "Package validation failed" error
- Run `twine check dist/*`
- Fix any metadata issues
- Rebuild package

#### Import errors after installation
- Check package structure
- Verify `__init__.py` files exist
- Test in clean environment

### Getting Help

- [PyPI Help](https://pypi.org/help/)
- [TestPyPI Help](https://test.pypi.org/help/)
- [Twine Documentation](https://twine.readthedocs.io/)
- [Python Packaging Guide](https://packaging.python.org/)

## Best Practices

1. **Always test on TestPyPI first**
2. **Use API tokens instead of passwords**
3. **Tag releases in git**
4. **Keep version numbers in sync**
5. **Test in clean environments**
6. **Use semantic versioning**
7. **Automate with GitHub Actions**
8. **Document changes in releases**