Mathias Beaulieu-Duncan
57c9aa6e00
Some checks failed
Publish NuGet Packages / build-and-publish (push) Failing after 41s
135 lines
3.5 KiB
Markdown
135 lines
3.5 KiB
Markdown
# 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
|