# Release Guide

This guide explains how to publish new versions of the Svrnty.GeoManagement NuGet packages.

## Prerequisites

✅ All tests passing
✅ Changes committed and pushed to main branch
✅ `NUGET_API_KEY` configured in Gitea repository secrets

## Release Steps

### 1. Decide on Version Number

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

- **Major version** (x.0.0) - Breaking changes
- **Minor version** (0.x.0) - New features, backwards compatible
- **Patch version** (0.0.x) - Bug fixes, backwards compatible

**Pre-release suffixes:**
- `-alpha` - Early testing
- `-beta` - Feature complete, testing
- `-rc.1` - Release candidate

**Examples:**
- `1.0.0` - First stable release
- `1.1.0` - New features added
- `1.1.1` - Bug fix
- `2.0.0-beta.1` - Major version beta

### 2. Create and Push Git Tag

```bash
# Create tag (WITHOUT 'v' prefix)
git tag 1.0.0

# Push tag to trigger CI/CD
git push origin 1.0.0
```

### 3. Monitor Workflow

1. Go to your Gitea repository
2. Navigate to **Actions** tab
3. Watch the **"Publish NuGet Packages"** workflow run
4. Verify all steps complete successfully:
   - ✅ Checkout code
   - ✅ Setup .NET
   - ✅ Build solution
   - ✅ Run tests
   - ✅ Pack packages
   - ✅ Publish to NuGet.org

### 4. Verify on NuGet.org

After 5-10 minutes, check:
- https://www.nuget.org/packages/Svrnty.GeoManagement.Abstractions
- https://www.nuget.org/packages/Svrnty.GeoManagement.Google

## What Gets Published

Both packages are **always published together** with the same version:

1. **Svrnty.GeoManagement.Abstractions** - Core interfaces and models
2. **Svrnty.GeoManagement.Google** - Google provider implementation

## Workflow Details

The Gitea workflow (`.gitea/workflows/publish-nuget.yml`):

- **Trigger**: Any tag matching `[0-9]+.[0-9]+.[0-9]+*` pattern
- **Tag format**: Direct version number (e.g., `1.0.0`, not `v1.0.0`)
- **Quality gates**: Tests must pass before publish
- **Artifacts**: Packages uploaded to workflow artifacts for download

## Troubleshooting

### Workflow didn't trigger
- Verify tag format matches pattern (e.g., `1.0.0`, not `v1.0.0`)
- Check if tag was pushed: `git push origin --tags`

### Tests failed
- Run tests locally: `dotnet test`
- Fix issues and create new tag with next patch version

### Publish failed
- Check `NUGET_API_KEY` secret is configured in Gitea
- Verify API key has push permissions
- Check if version already exists on NuGet.org (use `--skip-duplicate`)

### Want to unpublish
- NuGet.org doesn't allow deletion, only unlisting
- Publish new patch version with fix instead

## Local Testing

Test package creation before releasing:

```bash
# Build Release configuration
dotnet build --configuration Release

# Create packages locally
dotnet pack Svrnty.GeoManagement.Abstractions -c Release -p:Version=1.0.0-local
dotnet pack Svrnty.GeoManagement.Google -c Release -p:Version=1.0.0-local

# Check package contents
dotnet nuget verify Svrnty.GeoManagement.Abstractions/bin/Release/*.nupkg
dotnet nuget verify Svrnty.GeoManagement.Google/bin/Release/*.nupkg
```

## Rollback a Release

If you need to rollback:

1. **Unlist the package** on NuGet.org (doesn't delete it)
2. **Publish a new patch version** with the fix
3. **Update documentation** to recommend the new version

## Version Increment Examples

Starting from `1.2.3`:

- Bug fix → `1.2.4`
- New feature → `1.3.0`
- Breaking change → `2.0.0`
- Beta for next major → `2.0.0-beta.1`

## Questions?

- Check workflow logs in Gitea Actions tab
- Review `CLAUDE.md` for development guidance
- See `TESTING.md` for test setup