feat: enhance CI/CD pipeline and add release process documentation

2026-03-29 20:34:56 +02:00
parent 9f24573dc0
commit 1c44afaae4
9 changed files with 494 additions and 33 deletions
@@ -0,0 +1,122 @@
+<!-- cspell:ignore Gitea -->
+
+# Releasing go-lib/certs
+
+This document describes the process for creating a release of the
+`go-lib/certs` library.
+
+The repository currently has the released tag `v0.0.2`. The next
+release created from the current main branch should therefore use the
+next patch version, for example `v0.0.3`, unless you intentionally
+introduce a breaking or feature-level version bump.
+
+## Overview
+
+Releases in this project are managed via Git tags. When you push a
+tag matching the pattern `v*` (for example, `v0.0.3`), the Drone
+pipeline automatically:
+
+1. Runs quality checks (tests, coverage gate, vet, vulnerability scan)
+2. Generates release notes from commits
+3. Creates a source archive (`sources.tar.gz`)
+4. Publishes a release to Gitea with attached artifacts
+
+## Versioning
+
+This library follows semantic versioning: `MAJOR.MINOR.PATCH`
+(for example, `v1.2.3`).
+
+- `v1.0.0`: breaking API changes
+- `v1.1.0`: backward-compatible features
+- `v1.0.1`: backward-compatible fixes
+
+## Prerequisites
+
+Before creating a release, ensure:
+
+1. Working tree is clean (`git status`)
+2. Tests pass locally (`go test ./...`)
+3. Coverage is at least 80%
+4. Dependencies are tidy (`go mod tidy`)
+5. Documentation is up to date (README/docs)
+
+## Create a Release
+
+### 1. Prepare (optional)
+
+Update docs, examples, or changelog if needed:
+
+```bash
+git add README.md CHANGELOG.md docs/
+git commit -m "docs: prepare release"
+```
+
+### 2. Create tag
+
+```bash
+git tag -a v0.0.3 -m "Release v0.0.3"
+```
+
+### 3. Push tag
+
+```bash
+git push origin v0.0.3
+```
+
+### 4. Verify pipeline and release
+
+After pushing the tag, verify in Drone and Gitea:
+
+- Pipeline succeeded for tag build
+- Gitea release exists with artifacts:
+  - `.build/coverage.txt`
+  - `.build/sources.tar.gz`
+  - `.build/release-notes.md`
+
+## Install Released Version
+
+```bash
+# latest
+go get scm.yoorie.de/go-lib/certs
+
+# specific
+go get scm.yoorie.de/go-lib/certs@v0.0.3
+```
+
+## Troubleshooting
+
+### Coverage below threshold
+
+Run locally and inspect uncovered code:
+
+```bash
+go test -v -coverprofile .build/coverage.out ./...
+go tool cover -func .build/coverage.out
+```
+
+### Release step fails
+
+Common causes:
+
+- Missing Drone secret `gitea_token`
+- Tag does not match `v*`
+- Earlier pipeline step failed
+
+### Wrong tag pushed
+
+```bash
+git tag -d v0.0.3
+git push origin :refs/tags/v0.0.3
+```
+
+Then create and push the corrected tag.
+
+## Release Checklist
+
+- [ ] Tests pass locally
+- [ ] Coverage is at least 80%
+- [ ] `go vet ./...` passes
+- [ ] `govulncheck ./...` is clean or reviewed
+- [ ] Tag `vX.Y.Z` created and pushed
+- [ ] Drone pipeline succeeded
+- [ ] Gitea release contains expected artifacts