# Releasing go-lib/micro

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

## Overview

Releases in this project are managed via Git tags. When you push a
tag matching the pattern `v*` (for example, `v0.2.0`), 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 docs/
git commit -m "docs: prepare release"
```

### 2. Create tag

```bash
git tag -a v0.2.0 -m "Release v0.2.0"
```

### 3. Push tag

```bash
git push origin v0.2.0
```

### 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/micro

# specific
go get scm.yoorie.de/go-lib/micro@v0.2.0
```

## 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.2.0
git push origin :refs/tags/v0.2.0
```

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