From 0ebb212b659bc1d572323bc29d3f005daffb5604 Mon Sep 17 00:00:00 2001
From: Stefan <stefan.goppelt@yoorie.de>
Date: Sun, 29 Mar 2026 16:27:41 +0200
Subject: [PATCH] docs: add release process documentation

---
 docs/RELEASING.md | 180 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 180 insertions(+)
 create mode 100644 docs/RELEASING.md

diff --git a/docs/RELEASING.md b/docs/RELEASING.md
new file mode 100644
index 0000000..b7571dd
--- /dev/null
+++ b/docs/RELEASING.md
@@ -0,0 +1,180 @@
+# 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/)