felladrin / felladrin/MiniSearch

community: add semantic versioning tags to releases

Closed
#2,523 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
587
Forks
70
Avg merge
1h 42m
Merged PRs (30d)
184

Description

## Problem

The project has no semantic versioning tags. Releases are published as Docker images with:

- `latest` (moves on every release)
- `YYYY.M.D-` (immutable, e.g., `2026.8.31-abc1234`)

There are no git tags (verified: `git tag -l` returns empty).

## Why It Matters

- **No git tags**: Contributors can't checkout a specific release
- **No semantic versioning**: Users can't express version constraints (e.g., ">=1.0.0 <2.0.0")
- **Hard to reference**: PRs and issues can't reference a specific release version
- **Rollback is manual**: Self-hosters must remember the exact date-sha tag

## Current Release Process

1. Maintainer runs `gh workflow run publish-docker-image.yml`
2. Docker image is tagged `latest` and `YYYY.M.D-`
3. No git tag is created
4. No GitHub Release is created
5. No CHANGELOG entry is added (see #2511)

## Proposed Solution

Add semantic versioning to the release process:

### Option 1: CalVer (Calendar Versioning)

Use the existing date-based scheme but add it as a git tag:

```bash
git tag -a "2026.8.31" -m "Release 2026.8.31"
git push origin "2026.8.31"
```

### Option 2: SemVer (Semantic Versioning)

Use major.minor.patch versioning:

```bash
git tag -a "v1.0.0" -m "Release v1.0.0"
git push origin "v1.0.0"
```

Then update the Docker publish workflow to use the git tag as the image tag.

### Option 3: Hybrid

Use both: `v1.0.0` for semver and `2026.8.31-v1.0.0` for the Docker image.

## Recommended Approach

1. **Start with CalVer** (less disruptive, matches existing scheme)
2. Create a git tag for each release
3. Create a GitHub Release with release notes
4. Update the Docker publish workflow to use the git tag
5. Add a CHANGELOG entry (see #2511)

## Files to Change

- `.github/workflows/publish-docker-image.yml` (add git tagging)
- New: Release process documentation in `docs/` or `CONTRIBUTING.md`

## Acceptance Criteria

- Git tags are created for each release
- GitHub Releases are created with release notes
- Docker images are tagged with the release version
- README documents how to pin to a specific version
- CHANGELOG is updated with each release (see #2511)

Contributor guide

Open the contributing guide

Research direction

Start by reading .github/workflows/publish-docker-image.yml and the current release steps in the issue. Decide how the proposed CalVer approach fits the existing date-SHA image tags, then review README, docs/ or CONTRIBUTING.md, and the related CHANGELOG issue #2511. Done means releases create git and GitHub tags, publish versioned Docker images, document pinning, and include release notes.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, git, github-actions
Domain
ci-cd, devops, documentation, release
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.