# Release Process

This document outlines the release process for AtomIngest using GitFlow-style release branches.

## Release Types

### 1. Regular Release
- Created from `develop` or `main` branch
- Uses `release/x.y.z` branch naming
- Automatically publishes to TestPyPI when branch is pushed
- Publishes to PyPI when tag is created

### 2. Hotfix Release
- Created from `main` branch for urgent fixes
- Uses `hotfix/x.y.z` branch naming
- Same publishing flow as regular releases

## Quick Start

### Using the Release Script (Recommended)

```bash
# Check current status
python release.py status

# Start a new release
python release.py start 0.1.0

# Make final adjustments, then finish the release
python release.py finish 0.1.0

# Create a hotfix
python release.py hotfix 0.1.1
```

### Manual Process

1. **Create Release Branch**
   ```bash
   git checkout develop  # or main
   git pull origin develop
   git checkout -b release/0.1.0
   ```

2. **Update Version**
   - Edit `pyproject.toml` version field
   - Edit `atomingest/__init__.py` __version__ variable
   - Commit changes

3. **Push Release Branch**
   ```bash
   git push -u origin release/0.1.0
   ```
   This triggers automatic TestPyPI publishing via GitHub Actions.

4. **Final Testing**
   - Test the package from TestPyPI:
     ```bash
     pip install --index-url https://test.pypi.org/simple/ atomingest
     ```

5. **Finish Release**
   ```bash
   # Merge to main
   git checkout main
   git merge --no-ff release/0.1.0
   git tag -a v0.1.0 -m "Release version 0.1.0"
   git push origin main
   git push origin v0.1.0

   # Merge to develop (if exists)
   git checkout develop
   git merge --no-ff release/0.1.0
   git push origin develop

   # Clean up
   git branch -d release/0.1.0
   git push origin --delete release/0.1.0
   ```

## Automated Publishing

### TestPyPI Publishing
- **Trigger**: Push to any `release/*` branch
- **Purpose**: Testing and validation before production release
- **Installation**: `pip install --index-url https://test.pypi.org/simple/ atomingest`

### PyPI Publishing
- **Trigger**: Push of version tags (e.g., `v0.1.0`)
- **Purpose**: Production release
- **Installation**: `pip install atomingest`

### Manual Publishing
You can manually trigger publishing via GitHub Actions:
1. Go to the Actions tab in GitHub
2. Select "Publish to PyPI" workflow
3. Click "Run workflow"
4. Choose TestPyPI or PyPI

## Version Numbering

Follow [Semantic Versioning](https://semver.org/):
- **MAJOR.MINOR.PATCH** (e.g., 1.0.0)
- **Pre-release**: Add suffix (e.g., 1.0.0-beta.1, 1.0.0-rc.1)

### Examples:
- `0.1.0` - First beta release
- `1.0.0` - First stable release
- `1.0.1` - Hotfix release
- `1.1.0` - Minor feature release
- `2.0.0` - Breaking changes release

## Release Checklist

### Pre-Release
- [ ] All tests pass in CI
- [ ] Documentation is updated
- [ ] CHANGELOG.md is updated
- [ ] Version numbers are consistent
- [ ] Dependencies are properly specified

### During Release
- [ ] Release branch created from correct source
- [ ] Version bumped in all necessary files
- [ ] TestPyPI package installs correctly
- [ ] All features work as expected

### Post-Release
- [ ] PyPI package is available
- [ ] GitHub release is created with notes
- [ ] Documentation sites are updated
- [ ] Team is notified of release

## Rollback Procedure

If you need to rollback a release:

1. **Remove PyPI package** (contact PyPI support if necessary)
2. **Delete the tag**:
   ```bash
   git tag -d v0.1.0
   git push origin :refs/tags/v0.1.0
   ```
3. **Revert the merge commit** on main:
   ```bash
   git checkout main
   git revert -m 1 <merge-commit-hash>
   git push origin main
   ```

## GitHub Secrets Required

For automated publishing, ensure these secrets are set in GitHub:

- `PYPI_API_TOKEN` - Production PyPI token
- `TEST_PYPI_API_TOKEN` - TestPyPI token
- `CODECOV_TOKEN` - Code coverage reporting (optional)

## Troubleshooting

### Build Failures
- Check `pyproject.toml` syntax
- Ensure all dependencies are available
- Verify version format is correct

### Publishing Failures
- Check API tokens are valid and have correct permissions
- Ensure package name is available on PyPI
- Verify version doesn't already exist

### Version Conflicts
- Use `python release.py status` to check current state
- Ensure you're on the correct branch
- Check for uncommitted changes

## Branch Protection

Consider setting up branch protection rules:

### Main Branch
- Require pull request reviews
- Require status checks to pass
- Restrict pushes to release managers

### Develop Branch
- Require pull request reviews
- Allow direct pushes for release merges
- Require up-to-date branches

This ensures a clean, traceable release process.
