Critical: Implement Git tagging strategy with semantic versioning

[tbrandenburg]

Problem

The repository has zero Git tags despite active development with 296+ pull requests. This creates critical operational issues:

• Impossible to create reproducible deployments
• No way to identify stable release points
• Cannot roll back to known-good versions
• Unable to correlate runtime issues with source code

Evidence

• git tag --list returns empty
• Commit history shows no version markers
• No release points defined

Impact

Critical - Without tags, production deployments become unreproducible and unreliable.

Recommended Solution

1. Adopt semantic versioning (e.g., v1.0.0, v1.1.0, v2.0.0)
2. Tag current stable state as v0.1.0
3. Implement automated tagging in CI/CD pipeline

Acceptance Criteria

• Create initial v0.1.0 tag for current codebase
• Document versioning strategy in README
• Set up automated tagging workflow for future releases
• Ensure tags follow semantic versioning format

Priority

Critical - Blocks reliable production deployments

[github-actions]

Investigation: Critical: Implement Git tagging strategy with semantic versioning

Issue: #299 (#299)
Type: ENHANCEMENT
Investigated: 2026-03-15T12:00:00Z

Assessment

Metric	Value	Reasoning
Priority	HIGH	Issue explicitly marked "Critical" - blocks reliable production deployments and has been requested by maintainer
Complexity	LOW	Only 2-3 files to modify: add tag, update README, create CI workflow - no architectural changes
Confidence	HIGH	Clear requirements: create v0.1.0 tag, document strategy, add CI workflow

---

Problem Statement

The repository has zero Git tags despite active development with 296+ pull requests. This creates critical operational issues:

• Impossible to create reproducible deployments
• No way to identify stable release points
• Cannot roll back to known-good versions
• Unable to correlate runtime issues with source code

---

Analysis

Root Cause / Change Rationale

This is an enhancement issue, not a bug. The "root cause" is simply that no one has implemented a tagging strategy yet. The fix requires:

1. Creating an initial Git tag to establish the baseline
2. Documenting the versioning approach
3. Automating future tagging via CI/CD

Evidence

• git tag --list returns empty (verified)
• Commit history shows active development (296+ PRs merged)
• No existing CI/CD workflow for releases
• README.md has no versioning section (lines 1-258)

Affected Files

File	Lines	Action	Description
README.md	ADD	UPDATE	Add versioning section
.github/workflows/release.yml	NEW	CREATE	Automated release workflow
Makefile	14	UPDATE	Add release targets

Integration Points

• GitHub Actions (existing .github/workflows/)
• Existing CI workflows run on push to main branch
• Makefile already has build and test targets

Git History

• Last commit: d52f551 - "Merge pull request Show workflow stderr in Tasks diagnostics #298"
• PR count: 296+ merged
• Implication: Active project needs tagging for production readiness

---

Implementation Plan

Step 1: Create initial Git tag

Action: CREATE TAG
Command: git tag -a v0.1.0 -m "Initial release v0.1.0"

Why: Establishes baseline for reproducible deployments and enables future automation

---

Step 2: Add versioning documentation to README

File: README.md
Lines: ADD after line 255 (before "Maintainers" section)
Action: UPDATE

Section to add:

## Versioning

This project uses [Semantic Versioning](https://semver.org/) (SemVer).

### Version Format

Given a version number `MAJOR.MINOR.PATCH`:
- **MAJOR** - Incompatible API changes
- **MINOR** - New functionality (backwards compatible)
- **PATCH** - Bug fixes (backwards compatible)

### Release Tags

All releases are tagged in Git with the format `v{version}` (e.g., `v1.0.0`).

### Latest Release

Check the latest tag:
```bash
git fetch --tags
git checkout v0.1.0

CI/CD Automated Releases

Releases are automated via GitHub Actions. On push to main with a version tag:

1. Tests run
2. Build completes
3. Git tag is created (manual process)
4. Release artifacts are published

Manual Release Process

# Update version in code if needed
# Run tests
make qa

# Create annotated tag
git tag -a v0.1.0 -m "Release v0.1.0"

# Push tag to remote
git push origin v0.1.0

**Why**: Documents the versioning strategy for contributors and enables reproducibility

---

### Step 3: Create automated release workflow

**File**: `.github/workflows/release.yml`
**Action**: CREATE

**Content:**

```yaml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    name: Create Release
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install UV
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Install dependencies
        run: make install

      - name: Run tests
        run: make test

      - name: Build frontend
        run: npm run build

      - name: Build backend
        run: make build

      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref_name }}
          release_name: Release ${{ github.ref_name }}
          draft: false
          prerelease: ${{ contains(github.ref_name, 'alpha') || contains(github.ref_name, 'beta') }}

Why: Automates release process when version tags are pushed

---

Step 4: Add release targets to Makefile

File: Makefile
Lines: ADD to help section (around line 37) and targets
Action: UPDATE

Add to help text after line 37:

echo "  release     Create and push a new release tag"

Add new target:

release:
	@echo "📦 Creating release..."
	@read -p "Enter version (e.g., v0.1.0): " VERSION; \
	if [ -z "$$VERSION" ]; then \
		echo "❌ Version is required"; \
		exit 1; \
	fi; \
	echo "🏷️  Creating tag $$VERSION..."; \
	git tag -a $$VERSION -m "Release $$VERSION"; \
	echo "🚀 Pushing tag to remote..."; \
	git push origin $$VERSION; \
	echo "✅ Release $$VERSION created and pushed"

Why: Provides easy CLI interface for creating releases

---

Patterns to Follow

From existing workflow - mirror tests.yml:1-16:

name: Tests

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

This pattern shows the workflow trigger structure.

From README.md - document style:

## Section Title

Description and code blocks following existing format.

---

Edge Cases & Risks

Risk/Edge Case	Mitigation
Tag format incorrect	CI workflow only triggers on v* pattern
Tests fail on release	Workflow runs tests before release
Accidental tag push	Require PR review for main branch protection
No semantic version increments	Document SemVer rules in README

---

Validation

Automated Checks

# Verify no existing tags (should show empty)
git tag --list

# After implementing - verify tag creation
git tag -a v0.1.0 -m "Test tag"
git tag --list | grep v0.1.0

# Verify workflow syntax
npm run lint  # N/A for YAML, but check with YAML linter if available

# Verify README renders correctly
# (manual: view markdown preview)

Manual Verification

1. Create test tag locally: git tag -a v0.1.0-test -m "Test"
2. Verify tag exists: git tag --list | grep v0.1.0
3. Delete test tag: git tag -d v0.1.0-test
4. Verify README sections are properly formatted
5. Verify workflow file is valid YAML

---

Scope Boundaries

IN SCOPE:

• Creating initial v0.1.0 tag
• Documenting versioning in README
• Creating CI workflow for automated releases
• Adding Makefile release targets

OUT OF SCOPE (do not touch):

• Version numbers in code (package.json, pyproject.toml)
• Actual release process beyond tagging
• Docker image versioning
• CHANGELOG generation

---

Metadata

• Investigated by: GHAR
• Timestamp: 2026-03-15T12:00:00Z
• Artifact: .ghar/issues/issue-299.md