# PyPI Release Guide for TrendSleuth

## Pre-Release Checklist

### 1. Code Quality
- [x] All tests passing (111/111)
- [x] No mypy errors
- [x] Code follows style guidelines
- [x] Type hints throughout codebase

### 2. Documentation
- [x] README.md is complete and accurate
- [x] Installation instructions updated for PyPI
- [x] Usage examples are clear
- [x] CHANGELOG.md updated with release notes
- [x] LICENSE file present (MIT)

### 3. Package Metadata
- [x] pyproject.toml has correct metadata
- [x] Version number set (0.1.0)
- [x] Author email updated
- [x] Keywords added
- [x] Classifiers added
- [x] Project URLs configured
- [x] Entry points configured (CLI command)

### 4. Dependencies
- [x] All dependencies listed in pyproject.toml
- [x] Version constraints appropriate
- [x] No example.com emails

### 5. Files
- [x] .gitignore includes build artifacts
- [x] py.typed marker file present
- [x] __init__.py files present
- [x] No sensitive data in repository

## Building the Package

### 1. Install Build Tools

```bash
pip install --upgrade build twine
```

### 2. Clean Previous Builds

```bash
rm -rf dist/ build/ *.egg-info
```

### 3. Build the Package

```bash
python -m build
```

This creates:
- `dist/trendsleuth-0.1.0.tar.gz` (source distribution)
- `dist/trendsleuth-0.1.0-py3-none-any.whl` (wheel distribution)

### 4. Check the Build

```bash
twine check dist/*
```

Should output: `Checking dist/trendsleuth-0.1.0.tar.gz: PASSED` etc.

### 5. Test Installation Locally

```bash
# Create a fresh virtual environment
python -m venv test-env
source test-env/bin/activate

# Install the built package
pip install dist/trendsleuth-0.1.0-py3-none-any.whl

# Test the CLI
trendsleuth --help

# Deactivate and remove test environment
deactivate
rm -rf test-env
```

## Publishing to PyPI

### Test PyPI (Recommended First)

1. **Register on Test PyPI:** https://test.pypi.org/account/register/

2. **Create API Token:**
   - Go to https://test.pypi.org/manage/account/#api-tokens
   - Create a token for "trendsleuth"
   - Save the token securely

3. **Upload to Test PyPI:**

```bash
twine upload --repository testpypi dist/*
```

Enter your token when prompted (username: `__token__`, password: your token)

4. **Test Installation from Test PyPI:**

```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ trendsleuth
```

Note: The `--extra-index-url` is needed because some dependencies aren't on Test PyPI.

### Production PyPI

1. **Register on PyPI:** https://pypi.org/account/register/

2. **Create API Token:**
   - Go to https://pypi.org/manage/account/#api-tokens
   - Create a token for "trendsleuth"
   - Save the token securely

3. **Upload to PyPI:**

```bash
twine upload dist/*
```

Enter your token when prompted (username: `__token__`, password: your token)

4. **Verify Installation:**

```bash
pip install trendsleuth
trendsleuth --help
```

## Post-Release

### 1. Tag the Release on GitHub

```bash
git tag -a v0.1.0 -m "Release version 0.1.0"
git push origin v0.1.0
```

### 2. Create GitHub Release

- Go to https://github.com/lukemaxwell/trendsleuth/releases
- Click "Create a new release"
- Select tag v0.1.0
- Title: "TrendSleuth v0.1.0"
- Copy the CHANGELOG content into the description
- Attach the distribution files (optional)

### 3. Update README Badge

Add a PyPI version badge to README.md:

```markdown
[![PyPI version](https://badge.fury.io/py/trendsleuth.svg)](https://badge.fury.io/py/trendsleuth)
```

### 4. Announce Release

- Post on Twitter/X
- Post on relevant subreddits (r/Python, r/commandline)
- Update personal website/blog
- Share in relevant Discord/Slack communities

## Configuration for CI/CD (Optional)

### GitHub Actions Auto-Publish

Create `.github/workflows/publish.yml`:

```yaml
name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build twine
      
      - name: Build package
        run: python -m build
      
      - name: Publish to PyPI
        env:
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
        run: twine upload dist/*
```

Add `PYPI_API_TOKEN` to GitHub repository secrets.

## Troubleshooting

### Build Errors

**Issue:** `ModuleNotFoundError` during build
- **Solution:** Ensure all imports use absolute paths from package root

**Issue:** Missing files in distribution
- **Solution:** Check `[tool.hatch.build.targets.*]` in pyproject.toml

### Upload Errors

**Issue:** `403 Forbidden`
- **Solution:** Check API token is correct and has appropriate scope

**Issue:** Package name already exists
- **Solution:** Choose a different name or contact PyPI support

**Issue:** Invalid distribution files
- **Solution:** Run `twine check dist/*` and fix reported issues

## Version Bumping for Future Releases

```bash
# For patch releases (0.1.0 -> 0.1.1)
# Update version in pyproject.toml
# Update CHANGELOG.md

# For minor releases (0.1.0 -> 0.2.0)
# Update version in pyproject.toml
# Update CHANGELOG.md

# For major releases (0.1.0 -> 1.0.0)
# Update version in pyproject.toml
# Update CHANGELOG.md
# Consider announcing breaking changes
```

## Resources

- [Python Packaging Guide](https://packaging.python.org/)
- [PyPI Help](https://pypi.org/help/)
- [Semantic Versioning](https://semver.org/)
- [Keep a Changelog](https://keepachangelog.com/)
