179 lines
4.5 KiB
Markdown
179 lines
4.5 KiB
Markdown
# Issue: Sync .version file with Git tag
|
|
|
|
## Title
|
|
Sync .version file with latest Git tag
|
|
|
|
## Labels
|
|
- `housekeeping`
|
|
- `versioning`
|
|
- `good first issue`
|
|
|
|
## Priority
|
|
**Low** (Non-blocking, cosmetic)
|
|
|
|
## Description
|
|
|
|
The `.version` file is out of sync with the latest Git tag, causing pre-commit warnings during development.
|
|
|
|
### Current State
|
|
- **`.version` file:** `v0.15.3`
|
|
- **Latest Git tag:** `v0.16.8`
|
|
|
|
### Impact
|
|
- Pre-commit hook `check-version-tag` fails with warning:
|
|
```
|
|
Check .version matches latest Git tag..................Failed
|
|
ERROR: .version (v0.15.3) does not match latest Git tag (v0.16.8)
|
|
```
|
|
- Does NOT block builds or affect runtime behavior
|
|
- Creates noise in pre-commit output
|
|
- May confuse contributors about the actual version
|
|
|
|
### Expected Behavior
|
|
- `.version` file should match the latest Git tag
|
|
- Pre-commit hook should pass without warnings
|
|
- Version information should be consistent across all sources
|
|
|
|
## Steps to Reproduce
|
|
|
|
1. Clone the repository
|
|
2. Run pre-commit checks:
|
|
```bash
|
|
pre-commit run --all-files
|
|
```
|
|
3. Observe warning: `.version (v0.15.3) does not match latest Git tag (v0.16.8)`
|
|
|
|
## Proposed Solution
|
|
|
|
### Option 1: Update .version to match latest tag (Quick Fix)
|
|
|
|
```bash
|
|
# Fetch latest tags
|
|
git fetch --tags
|
|
|
|
# Get latest tag
|
|
LATEST_TAG=$(git describe --tags --abbrev=0)
|
|
|
|
# Update .version file
|
|
echo "$LATEST_TAG" > .version
|
|
|
|
# Commit the change
|
|
git add .version
|
|
git commit -m "chore: sync .version file with latest Git tag ($LATEST_TAG)"
|
|
```
|
|
|
|
### Option 2: Automate version syncing (Comprehensive)
|
|
|
|
**Create a GitHub Actions workflow** to automatically sync `.version` with Git tags:
|
|
|
|
```yaml
|
|
name: Sync Version File
|
|
|
|
on:
|
|
push:
|
|
tags:
|
|
- 'v*'
|
|
|
|
jobs:
|
|
sync-version:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
|
|
- name: Update .version file
|
|
run: |
|
|
echo "${{ github.ref_name }}" > .version
|
|
|
|
- name: Commit and push
|
|
run: |
|
|
git config user.name "github-actions[bot]"
|
|
git config user.email "github-actions[bot]@users.noreply.github.com"
|
|
git add .version
|
|
git commit -m "chore: sync .version to ${{ github.ref_name }}"
|
|
git push
|
|
```
|
|
|
|
### Option 3: Remove .version file (Simplest)
|
|
|
|
If `.version` is not used in the codebase:
|
|
|
|
1. Delete `.version` file
|
|
2. Remove or update pre-commit hook to not check version sync
|
|
3. Use Git tags as the single source of truth for versioning
|
|
|
|
## Investigation Required
|
|
|
|
Before implementing, verify:
|
|
|
|
1. **Where is `.version` used?**
|
|
```bash
|
|
# Search codebase for references
|
|
grep -r "\.version" --exclude-dir=node_modules --exclude-dir=.git
|
|
```
|
|
|
|
2. **Is `.version` read by the application?**
|
|
- Check backend code for version file reads
|
|
- Check build scripts
|
|
- Check documentation generation
|
|
|
|
3. **Why is there a version discrepancy?**
|
|
- Was `.version` manually updated?
|
|
- Was it missed during release tagging?
|
|
- Is there a broken sync process?
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `.version` file matches latest Git tag (`v0.16.8`)
|
|
- [ ] Pre-commit hook `check-version-tag` passes without warnings
|
|
- [ ] Version consistency verified across all sources:
|
|
- [ ] `.version` file
|
|
- [ ] Git tags
|
|
- [ ] `package.json` (if applicable)
|
|
- [ ] `go.mod` (if applicable)
|
|
- [ ] Documentation
|
|
- [ ] If automated workflow is added:
|
|
- [ ] Workflow triggers on tag push
|
|
- [ ] Workflow updates `.version` correctly
|
|
- [ ] Workflow commits change to main branch
|
|
|
|
## Related Files
|
|
|
|
- `.version` — Version file (needs update)
|
|
- `.pre-commit-config.yaml` — Pre-commit hook configuration
|
|
- `CHANGELOG.md` — Version history
|
|
- `.github/workflows/` — Automation workflows (if Option 2 chosen)
|
|
|
|
## References
|
|
|
|
- **Pre-commit hook:** `check-version-tag`
|
|
- **QA Report:** `docs/reports/qa_report.md` (section 11.3)
|
|
- **Implementation Plan:** `docs/plans/current_spec.md`
|
|
|
|
## Priority Justification
|
|
|
|
**Why Low Priority:**
|
|
- Does not block builds or deployments
|
|
- Does not affect runtime behavior
|
|
- Only affects developer experience (pre-commit warnings)
|
|
- No security implications
|
|
- No user-facing impact
|
|
|
|
**When to address:**
|
|
- During next maintenance sprint
|
|
- When preparing for next release
|
|
- When cleaning up technical debt
|
|
- As a good first issue for new contributors
|
|
|
|
## Estimated Effort
|
|
|
|
- **Option 1 (Quick Fix):** 5 minutes
|
|
- **Option 2 (Automation):** 30 minutes
|
|
- **Option 3 (Remove file):** 15 minutes + investigation
|
|
|
|
---
|
|
|
|
**Created:** February 2, 2026
|
|
**Discovered During:** Docker build fix QA verification
|
|
**Reporter:** GitHub Copilot QA Agent
|
|
**Status:** Draft (not yet created in GitHub)
|