dotnet-geo-management/RELEASING.md

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:

• 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

# 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:

# 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