# Ducku Distribution Guide

This guide explains how to build, test, and distribute the ducku package.

## 🏗️ Building the Package

### Prerequisites

1. **Install build dependencies:**
   ```bash
   uv add --group build build twine
   # or with pip:
   pip install build twine
   ```

2. **Ensure all metadata is correct in `pyproject.toml`:**
   - Update version number
   - Check author information
   - Verify dependencies
   - Update repository URLs

### Build Process

1. **Clean previous builds:**
   ```bash
   rm -rf dist/ build/ *.egg-info/
   ```

2. **Build the package:**
   ```bash
   uv run python -m build
   # or with pip:
   python -m build
   ```

3. **Verify the build:**
   ```bash
   uv run python -m twine check dist/*
   ```

### Automated Build

Use the provided script:
```bash
./scripts/build.sh
```

## 🧪 Testing the Package

### Local Installation Test

1. **Install locally:**
   ```bash
   pip install dist/ducku-*.whl
   ```

2. **Test the command:**
   ```bash
   ducku --help
   PROJECT_PATH=/path/to/test/project ducku
   ```

3. **Automated test:**
   ```bash
   ./scripts/test_install.sh
   ```

## 📦 Distribution

### 1. Test PyPI (Recommended First)

Test your package on PyPI's test instance:

```bash
# Upload to test PyPI
uv run python -m twine upload --repository testpypi dist/*

# Test installation from test PyPI
pip install --index-url https://test.pypi.org/simple/ ducku
```

### 2. Production PyPI

Once tested, upload to production PyPI:

```bash
uv run python -m twine upload dist/*
```

### 3. GitHub Releases

1. Create a new release on GitHub
2. Upload the built files from `dist/` as release assets
3. Tag the release with the version number (e.g., `v0.1.0`)

## 🔐 Authentication

### PyPI API Tokens

1. Create account on [PyPI](https://pypi.org) and [Test PyPI](https://test.pypi.org)
2. Generate API tokens in account settings
3. Configure authentication:

**Option 1: Environment variables**
```bash
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=your_api_token_here
```

**Option 2: Keyring (Recommended)**
```bash
# Install keyring
pip install keyring

# Store tokens
python -m keyring set https://upload.pypi.org/legacy/ __token__
python -m keyring set https://test.pypi.org/legacy/ __token__
```

**Option 3: .pypirc file**
```ini
# ~/.pypirc
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = your_production_token

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = your_test_token
```

## 🚀 Release Checklist

Before each release:

- [ ] Update version in `pyproject.toml`
- [ ] Update `README.md` if needed
- [ ] Run all tests: `uv run pytest`
- [ ] Build package: `python -m build`
- [ ] Check package: `twine check dist/*`
- [ ] Test locally: `pip install dist/*.whl`
- [ ] Upload to test PyPI
- [ ] Test installation from test PyPI
- [ ] Upload to production PyPI
- [ ] Create GitHub release
- [ ] Update documentation

## 📋 Version Management

### Semantic Versioning

Follow [SemVer](https://semver.org/):
- `MAJOR.MINOR.PATCH`
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)

### Version Bumping

Update version in `pyproject.toml`:
```toml
[project]
version = "0.2.0"  # Update this
```

## 🛠️ Maintenance

### Regular Updates

1. **Dependencies**: Keep dependencies up to date
2. **Security**: Monitor for security vulnerabilities
3. **Python versions**: Update supported Python versions
4. **Documentation**: Keep README and docs current

### Monitoring

- Watch PyPI download statistics
- Monitor GitHub issues and discussions
- Track user feedback and feature requests

## 📞 Support

For distribution issues:
1. Check [PyPI Help](https://pypi.org/help/)
2. Read [Python Packaging Guide](https://packaging.python.org/)
3. Create issue in project repository
