How To: Implement Version Continuity from Polyrepos¶

Overview¶

This guide explains how to create baseline tags to continue versioning from the last polyrepo versions instead of starting fresh at v0.1.0.

Prerequisites¶

Git access to the monorepo
Permission to create and push tags
Understanding of GitVersion and conventional commits

Background¶

When services were migrated from polyrepos to the monorepo, the version history was preserved in git, but new versions started at v0.1.0. We need to create baseline tags so GitVersion continues from the last polyrepo versions.

Last Polyrepo Versions:

API: v8.20.1
PM: v10.44.1
Web: v4.1.5

Current Monorepo Versions:

API: api-v8.21.0
PM: pm-v10.45.0
Web: web-v5.0.0 (major bump due to many commits since v4.1.5)

Step-by-Step Implementation¶

Step 1: Find the Last Polyrepo Version Commits¶

These are the commits where the last polyrepo versions were tagged:

# Check API last version
git log --all --oneline --decorate | grep "v8.20.1"
# Output: f58380a1 (tag: v8.20.1) chore(api): bump ProjectManagement packages to 10.44.1

# Check PM last version
git log --all --oneline --decorate | grep "v10.44.1"
# Output: 24aed7c6 (tag: v10.44.1) perf(data-export): add periodic performance snapshots and fix tuple logging

# Check Web last version
git log --all --oneline --decorate | grep "v4.1.5"
# Output: 9f79cab5 (tag: v4.1.5) feat(i18n): prevent NG02100 by dynamic locale loading & fallback

Commit SHAs:

API v8.20.1: f58380a1
PM v10.44.1: 24aed7c6
Web v4.1.5: 9f79cab5

Step 2: Verify Commits Exist in Monorepo¶

# Verify each commit is in the monorepo history
git show f58380a1 --oneline
git show 24aed7c6 --oneline

# If Web v11.27.0 commit isn't found, search for it:
git log --all --oneline | grep -i "v11.27"

Step 3: Create Baseline Tags¶

Create prefixed tags at the same commits as the old unprefixed tags:

# Create API baseline tag
git tag -a api-v8.20.1 f58380a1 -m "Baseline: Continue from polyrepo v8.20.1"

# Create PM baseline tag
git tag -a pm-v10.44.1 24aed7c6 -m "Baseline: Continue from polyrepo v10.44.1"

# Create Web baseline tag
git tag -a web-v4.1.5 9f79cab5 -m "Baseline: Continue from polyrepo v4.1.5"

Step 4: Verify Tags Were Created¶

# List all service-prefixed tags
git tag | grep -E "^(api|pm|web)-v[0-9]+"

# Verify baseline tags point to correct commits
git show api-v8.20.1 --oneline
git show pm-v10.44.1 --oneline
git show web-v4.1.5 --oneline

Step 5: Push Baseline Tags to Origin¶

# Push individual baseline tags
git push origin api-v8.20.1
git push origin pm-v10.44.1
git push origin web-v4.1.5

# Or push all tags at once (be careful - this pushes ALL tags)
# git push origin --tags

Step 6: Test GitVersion Calculation¶

Make test commits to verify versions increment correctly:

# Test API versioning
git checkout master
git commit --allow-empty -m "feat(api): test version continuity"
# Expect: GitVersion calculates api-v8.21.0

# Test PM versioning
git commit --allow-empty -m "fix(pm): test version continuity"
# Expect: GitVersion calculates pm-v10.44.2

# Test Web versioning
git commit --allow-empty -m "feat(web): test version continuity"
# Expect: GitVersion calculates web-v5.1.0 (or higher)

To test locally without committing:

# Install GitVersion locally (if not already installed)
dotnet tool install --global GitVersion.Tool

# Test API version calculation
cd src/services/api
dotnet gitversion /config GitVersion.yml
# Look for "MajorMinorPatch": "8.21.0" or "8.20.2"

# Test PM version calculation
cd ../project-management
dotnet gitversion /config GitVersion.yml
# Look for "MajorMinorPatch": "10.45.0" or "10.44.2"

# Test Web version calculation
cd ../web
dotnet gitversion /config GitVersion.yml
# Look for "MajorMinorPatch": "5.0.0" or higher

Step 7: Clean Up Old v0.x Tags (Optional)¶

If you want to remove the old v0.x.x tags that started fresh:

# List old tags to delete
git tag | grep -E "^(api|pm|web)-v0\."

# Delete locally
git tag -d api-v0.1.0 api-v0.2.0 api-v0.2.1 api-v0.3.0 # ... etc
git tag -d pm-v0.1.0 pm-v0.2.0 pm-v0.2.1
git tag -d web-v0.1.0 web-v0.2.0 web-v0.2.1 web-v0.3.0

# Delete from remote (be VERY careful with this command!)
git push origin --delete api-v0.1.0 api-v0.2.0 # ... etc

# Or script it (DANGEROUS - verify first!)
# git tag | grep -E "^(api|pm|web)-v0\." | xargs git tag -d
# git push origin --delete $(git tag | grep -E "^(api|pm|web)-v0\.")

⚠️ WARNING: Only delete v0.x tags if:

They haven't been deployed to production
No Docker images reference these versions
No documentation references these versions
You have backups or the repo is backed up

Step 8: Update Documentation¶

Mark the work item as complete:

Update /docs/planning/migration/backlog.md - check off version continuity acceptance criteria
Verify ADR-004 is accurate
Verify CLAUDE.md reflects correct current versions
Update any release notes or changelogs

Troubleshooting¶

GitVersion Doesn't Recognize Baseline Tags¶

Problem: GitVersion still calculates v0.x.x versions

Solution:

Verify tag format matches tag-prefix in GitVersion.yml:

tag-prefix: 'api-v'  # or pm-v, web-v, etc.

Verify tag exists and is pushed to origin:

git tag | grep api-v8.20.1
git ls-remote --tags origin | grep api-v8.20.1

Ensure tag is reachable from current branch:

git tag --merged master | grep api-v8.20.1

Version Calculation is Wrong¶

Problem: GitVersion calculates unexpected version (e.g., api-v8.20.0 instead of api-v8.21.0)

Solution:

Check commits since baseline tag:

git log api-v8.20.1..HEAD --oneline

Verify conventional commit format:
feat: → minor version bump
fix: → patch version bump
chore:, docs:, style: → no version bump
Run GitVersion with verbose logging:

dotnet gitversion /verbosity Diagnostic

Web Service v4.1.5 Commit¶

Note: The correct last polyrepo version for syrf-web is v4.1.5, not v11.27.0 (which belongs to other services).

Verification:

# Find v4.1.5 tag
git show v4.1.5 --oneline
# Output: 9f79cab5 feat(i18n): prevent NG02100 by dynamic locale loading & fallback

# Create baseline tag
git tag -a web-v4.1.5 9f79cab5 -m "Baseline: Continue from polyrepo v4.1.5"

Verification Checklist¶

After implementation, verify:

Support¶

If you encounter issues:

Check the troubleshooting section above
Review the ADR-004 for context and rationale
Consult the GitVersion documentation: https://gitversion.net/docs/
Ask in team chat with details about the specific error