util/docs/RELEASING.md

# Releasing go-lib/util

This document describes the process for creating a release of the
`go-lib/util` library.

## Overview

Releases in this project are managed via **Git tags**. When you push a
tag matching the pattern `v*` (e.g., `v0.5.0`), the Drone CI/CD
pipeline automatically:

1. Runs all quality checks (tests, coverage, vet, vulnerability scan)
2. Creates a source archive (`sources.tar.gz`)
3. Publishes a release to Gitea with both artifacts

## Release Types

This library follows **semantic versioning**: `MAJOR.MINOR.PATCH` (e.g., `v1.2.3`)

- `v1.0.0` - Major release (breaking API changes)
- `v1.1.0` - Minor release (new features, backward compatible)
- `v1.0.1` - Patch release (bug fixes only)

## Prerequisites

Before creating a release, ensure:

1. **All changes committed**: `git status` shows clean working tree
2. **Tests passing**: Run `go test ./...` locally
3. **Coverage OK**: Coverage must be ≥ 80%
4. **Dependencies updated**: Run `go mod tidy`
5. **CHANGELOG.md updated** (optional but recommended)

## Creating a Release

### Step 1: Prepare Release Commit (Optional)

Update version references if needed (README, docs, etc.):

```bash
# Edit any version references
vim README.md
git add README.md
git commit -m "docs: prepare v0.5.0 release"
```

### Step 2: Create the Git Tag

```bash
# Create annotated tag with release notes
git tag -a v0.5.0 -m "Release v0.5.0: Description of changes"

# Or simple tag (not recommended)
# git tag v0.5.0
```

### Step 3: Push the Tag

```bash
# Push tag to remote
git push origin v0.5.0

# Or push all tags at once
# git push --tags
```

### Step 4: Monitor the Pipeline

1. Navigate to your Drone instance (usually `https://drone.example.com`)
2. Watch the pipeline run through:

   - ✓ Test & coverage checks
   - ✓ Code quality (vet, vulnerability scan)
   - ✓ Create source archive
   - ✓ Publish to Gitea release

### Step 5: Verify Release in Gitea

1. Go to your repository on Gitea
2. Click "Releases" section
3. Verify the new release includes:
   - Release title: `v0.5.0`
   - Attached artifacts:
     - `coverage.txt` - Test coverage report
     - `sources.tar.gz` - Full source code snapshot

## Using the Released Version

End users can install your library via:

```bash
# Latest version
go get scm.yoorie.de/go-lib/util

# Specific version
go get scm.yoorie.de/go-lib/util@v0.5.0

# Latest patch of a minor version
go get scm.yoorie.de/go-lib/util@v0.5
```

## Tag Naming Convention

- **Release tags**: `v0.5.0` (pushed to trigger Drone pipeline)
- **Pre-release tags** (optional): `v0.5.0-rc1`, `v0.5.0-beta1`
- **Internal tags** (if any): Not recommended; use branches instead

Only tags matching `v*` trigger the release pipeline.

## Rollback / Deleting a Release

If a release has issues:

```bash
# Delete local tag
git tag -d v0.5.0

# Delete remote tag
git push origin :refs/tags/v0.5.0

# Then push a fixed release with the same or new tag
git tag -a v0.5.0-fixed -m "Fixed release"
git push origin v0.5.0-fixed
```

## Troubleshooting

### Pipeline Failed

Check Drone logs:

1. Go to Drone UI
2. Click on failed pipeline
3. Expand step details
4. Review error messages

Common issues:

- **Coverage below 80%**: Ensure tests cover new code
- **Tests failing**: Run locally: `go test -v ./...`
- **Vet errors**: Run: `go vet ./...`

### Release Not Appearing in Gitea

1. Verify `gitea_token` secret is set in Drone
2. Check Drone pipeline output for release step
3. Ensure tag matches pattern `v*`

### Tag Already Exists

If you pushed a tag and need to update it:

```bash
# Force delete and recreate (dangerous - use with caution)
git tag -d v0.5.0
git push origin :refs/tags/v0.5.0
git tag -a v0.5.0 -m "Updated release notes"
git push origin v0.5.0
```

## Release Checklist

- [ ] All code changes reviewed and merged
- [ ] Tests pass locally: `go test -v ./...`
- [ ] Coverage ≥ 80%: Test and check coverage
- [ ] Code quality OK: `go vet ./...`
- [ ] No vulnerabilities: `govulncheck ./...`
- [ ] Dependencies tidy: `go mod tidy`
- [ ] CHANGELOG updated (if maintained)
- [ ] Version references updated (if any)
- [ ] Git tag created: `git tag -a vX.Y.Z -m "message"`
- [ ] Tag pushed: `git push origin vX.Y.Z`
- [ ] Release visible in Gitea
- [ ] Coverage artifact downloaded and verified

## Further Reading

- [Semantic Versioning](https://semver.org/)
- [Go Modules](https://golang.org/doc/modules)
- [Drone CI Documentation](https://docs.drone.io/)