# Publishing MCA SDK v0.8.21

## Prerequisites

1. **Authentication**: Ensure you have GitLab token or PyPI credentials configured
2. **Permissions**: Verify you have maintainer access to the package repository
3. **Testing**: All tests should pass before publishing

## Step 1: Push Release to Git Remote

```bash
# Push the commits and tag to remote
git push origin development
git push origin v0.8.21
```

This will:
- Push the endpoint fix commit
- Push the documentation update commit  
- Push the v0.8.21 tag

## Step 2: Publish to Package Repository

### Option A: GitLab Package Registry (Internal)

The `.pypirc` file is configured for GitLab:

```bash
# Install twine if not already installed
pip install twine

# Upload to GitLab package registry
python3 -m twine upload --repository gitlab dist/mca_sdk-0.8.21-py3-none-any.whl
```

**Note:** You'll need to set `CI_JOB_TOKEN` or configure a personal access token.

### Option B: PyPI (Public)

If publishing to public PyPI:

```bash
# Upload to PyPI
python3 -m twine upload dist/mca_sdk-0.8.21-py3-none-any.whl

# Or upload to TestPyPI first for verification
python3 -m twine upload --repository testpypi dist/mca_sdk-0.8.21-py3-none-any.whl
```

### Option C: Manual Distribution

For Vertex AI Workbench or internal deployment:

```bash
# Copy wheel to shared location
cp dist/mca_sdk-0.8.21-py3-none-any.whl /path/to/shared/packages/

# Users can install with:
pip install /path/to/shared/packages/mca_sdk-0.8.21-py3-none-any.whl
```

## Step 3: Verify Installation

Test the published package:

```bash
# Create a clean virtual environment
python3 -m venv test_env
source test_env/bin/activate

# Install from published source
pip install mca-sdk==0.8.21

# Verify version
python3 -c "import mca_sdk; print(mca_sdk.__version__)"

# Test registry endpoint
python3 -c "
from mca_sdk.registry import RegistryClient
# Should use /api/v1/configs endpoint
"
```

## Step 4: Notify Users

1. **Update internal documentation** with the new version
2. **Notify teams** using the SDK about the critical fix
3. **Share release notes**: `RELEASE_NOTES_v0.8.21.md`

### Example Notification

```
Subject: [ACTION REQUIRED] MCA SDK v0.8.21 - Critical Registry Fix

Team,

A critical fix for the MCA SDK has been released as v0.8.21.

ISSUE: v0.8.6-v0.8.9 had a registry endpoint bug causing all model 
config fetches to fail with 404 errors.

FIX: v0.8.21 reverts to the working endpoint.

ACTION: Please upgrade:
  pip install --upgrade mca-sdk==0.8.21

No code changes required. All registered models will now fetch successfully.

See RELEASE_NOTES_v0.8.21.md for details.
```

## Step 5: Update Workbench Environments

For users on Google Vertex AI Workbench:

```bash
# SSH to workbench or run in notebook
cd ~/sdk/mca-prototype
git pull origin development
git checkout v0.8.21
pip install --upgrade -e .

# Verify
python sdk-examples/internal-model/instrumented_model.py
```

## Troubleshooting

### Authentication Failed

If twine upload fails with authentication error:

```bash
# Set GitLab token
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=your-gitlab-token

# Try upload again
python3 -m twine upload --repository gitlab dist/mca_sdk-0.8.21-py3-none-any.whl
```

### Version Already Exists

If the version already exists in the registry:

```bash
# Check what's published
pip index versions mca-sdk

# If needed, increment to 0.8.11 and rebuild
```

### Package Not Found After Upload

Wait a few minutes for package registry to sync, then:

```bash
# Clear pip cache
pip cache purge

# Try install again
pip install --no-cache-dir mca-sdk==0.8.21
```

## Post-Release Checklist

- [ ] Git commits and tag pushed to origin
- [ ] Package published to registry
- [ ] Installation verified in clean environment
- [ ] Teams notified of the release
- [ ] Workbench environments updated
- [ ] Release notes shared
- [ ] README badge updated (already done)
- [ ] Any internal tracking systems updated

## Rollback Plan

If issues are discovered with v0.8.21:

```bash
# Users can downgrade to v0.8.5 (last known good version)
pip install mca-sdk==0.8.5

# Or pin to v0.8.5 in requirements.txt
echo "mca-sdk==0.8.5" >> requirements.txt
```
