felladrin / felladrin/MiniSearch
community: add semantic versioning tags to releases
- 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
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