# Release Instructions for CaDaR

## Quick Reference

This document provides quick instructions for releasing new versions of CaDaR to PyPI and updating documentation.

## Prerequisites (One-Time Setup)

Follow the detailed instructions in [SETUP_GITHUB_ACTIONS.md](SETUP_GITHUB_ACTIONS.md) to:

1. ✅ Create PyPI API token
2. ✅ Add `PYPI_API_TOKEN` to GitHub Secrets
3. ✅ Enable GitHub Pages (Source: GitHub Actions)
4. ✅ Set workflow permissions to "Read and write"

## Releasing a New Version

### Step 1: Push Code to GitHub

Since you haven't pushed yet due to authentication:

```bash
# Option 1: Use SSH (recommended)
git remote set-url origin git@github.com:Oit-Technologies/CaDaR.git
git push -u origin main

# Option 2: Use GitHub CLI
gh auth login
git push -u origin main

# Option 3: Use personal access token
# GitHub will prompt for username and token
git push -u origin main
```

### Step 2: Create a Release

Once your code is on GitHub, create a release tag:

```bash
# 1. Update CHANGELOG.md with your changes
vim CHANGELOG.md

# 2. Commit the changelog
git add CHANGELOG.md
git commit -m "Update CHANGELOG for v0.1.0"
git push origin main

# 3. Create and push the tag
git tag -a v0.1.0 -m "Release version 0.1.0"
git push origin v0.1.0
```

### Step 3: Monitor Automated Workflows

After pushing the tag, GitHub Actions will automatically:

1. **Build wheels** for all platforms (Linux, macOS, Windows)
2. **Publish to PyPI** at https://pypi.org/project/cadar/
3. **Build documentation** and deploy to GitHub Pages
4. **Create GitHub release** with downloadable wheels

Monitor progress:
- https://github.com/Oit-Technologies/CaDaR/actions

### Step 4: Verify Release

Check that everything worked:

- ✅ PyPI: https://pypi.org/project/cadar/0.1.0/
- ✅ Docs: https://oit-technologies.github.io/CaDaR/
- ✅ GitHub Release: https://github.com/Oit-Technologies/CaDaR/releases/tag/v0.1.0

## Tag Format

Tags must follow the format: `v*.*.*`

Examples:
- ✅ `v0.1.0` → PyPI version `0.1.0`
- ✅ `v1.2.3` → PyPI version `1.2.3`
- ✅ `v2.0.0-beta.1` → PyPI version `2.0.0-beta.1`
- ❌ `0.1.0` (missing 'v' prefix)
- ❌ `release-0.1.0` (wrong format)

## What Happens Automatically

### When you push a tag like `v0.1.0`:

#### PyPI Publishing (`.github/workflows/publish-pypi.yml`)

1. **Extracts version**: v0.1.0 → 0.1.0
2. **Updates files**:
   - `Cargo.toml`: version = "0.1.0"
   - `pyproject.toml`: version = "0.1.0"
3. **Builds wheels** for:
   - Linux: Python 3.8, 3.9, 3.10, 3.11, 3.12
   - macOS: Python 3.10, 3.11, 3.12
   - Windows: Python 3.10, 3.11, 3.12
4. **Publishes to PyPI**: All wheels uploaded
5. **Creates GitHub Release**: With downloadable wheels and release notes

#### Documentation (`.github/workflows/docs.yml`)

1. **Builds documentation**:
   - Generates Python API docs
   - Builds Rust docs
   - Creates MkDocs site
2. **Creates versioned docs**:
   - Main docs at root: `/`
   - Versioned docs: `/versions/0.1.0/`
3. **Updates version index**: Lists all available versions
4. **Deploys to GitHub Pages**

## Testing Locally

### Test Package Build

```bash
# Build wheel locally
source venv/bin/activate
maturin build --release

# Check the wheel
ls -lh target/wheels/
pip install target/wheels/cadar-*.whl --force-reinstall

# Test it
python -c "import cadar; print(cadar.ara2bizi('سلام', darija='Ma'))"
```

### Test Documentation

```bash
# Install docs dependencies
pip install mkdocs mkdocs-material mkdocstrings[python]

# Build and serve docs
cd docs
python generate_api_docs.py
mkdocs serve

# Open http://127.0.0.1:8000
```

## Common Issues

### "Authentication failed" when pushing

**Solution**: Set up SSH keys or use GitHub CLI:

```bash
# Using GitHub CLI (easiest)
gh auth login

# Using SSH
ssh-keygen -t ed25519 -C "your_email@example.com"
# Add the public key to GitHub: Settings → SSH and GPG keys
```

### "PYPI_API_TOKEN secret not found"

**Solution**: Add the secret in GitHub:
1. Go to Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Name: `PYPI_API_TOKEN`
4. Value: Your PyPI token

### "Permission denied" for GitHub Pages

**Solution**: Enable write permissions:
1. Settings → Actions → General
2. Workflow permissions → Read and write permissions
3. Save

### "Version already exists on PyPI"

**Solution**: Increment the version number. You cannot re-upload the same version.

```bash
# Change version and create new tag
git tag -a v0.1.1 -m "Release version 0.1.1"
git push origin v0.1.1
```

## Version Numbering

Follow [Semantic Versioning](https://semver.org/):

- **MAJOR** (1.0.0): Incompatible API changes
- **MINOR** (0.1.0): Add functionality (backwards-compatible)
- **PATCH** (0.0.1): Bug fixes (backwards-compatible)

Examples:
- `v0.1.0`: Initial release
- `v0.1.1`: Bug fix
- `v0.2.0`: New feature (backwards-compatible)
- `v1.0.0`: Stable API, possibly breaking changes from v0.x

## Release Checklist

Before creating a release:

- [ ] All tests pass: `cargo test`
- [ ] Python tests pass
- [ ] Update CHANGELOG.md with changes
- [ ] Update version in README badges (optional)
- [ ] Code is pushed to main branch
- [ ] Tag follows format: `v*.*.*`

After creating a release:

- [ ] Check GitHub Actions completed successfully
- [ ] Verify package on PyPI: `pip install cadar==0.1.0`
- [ ] Verify documentation deployed
- [ ] Test installation: `pip install cadar && python -c "import cadar"`
- [ ] Announce release (optional)

## Next Release Example

For version v0.1.1:

```bash
# 1. Make your changes
# ... code changes ...

# 2. Test
cargo test
source venv/bin/activate && python -m pytest

# 3. Update changelog
cat >> CHANGELOG.md << 'EOF'

## [0.1.1] - 2026-02-01

### Fixed
- Fixed bug in normalization stage
- Improved error messages

EOF

# 4. Commit changes
git add .
git commit -m "Fix normalization bug for v0.1.1"
git push origin main

# 5. Create and push tag
git tag -a v0.1.1 -m "Release version 0.1.1"
git push origin v0.1.1

# 6. Watch automation happen!
# Visit: https://github.com/Oit-Technologies/CaDaR/actions
```

## Support

- **Setup Help**: See [SETUP_GITHUB_ACTIONS.md](SETUP_GITHUB_ACTIONS.md)
- **GitHub Issues**: https://github.com/Oit-Technologies/CaDaR/issues
- **Documentation**: https://oit-technologies.github.io/CaDaR/

---

Happy releasing! 🚀
