Version Synchronization System

The version synchronization system ensures that all live version references remain consistent with dotfiles_version in defaults/.chezmoidata.toml. That manifest is the only hand-edited source; package.json, CLI metadata, discovery cards, and current documentation are generated release surfaces.

Overview

Problem Statement

Large repositories often have version numbers scattered across multiple files:

README badges
Documentation headers
Feature version stamps
Configuration files

Manually keeping these synchronized is error-prone and time-consuming.

Solution Architecture

This system provides automated version synchronization through:

CI/CD Workflow (.github/workflows/sync-versions.yml) - Automated synchronization on version changes
Local Script (scripts/version-sync.sh) - Manual synchronization and verification
Verification System - Ensures all references remain consistent

Components

1. GitHub Actions Workflow

Location: .github/workflows/sync-versions.yml

Triggers:

Push to main or a release branch when the canonical manifest changes
Pull requests affecting the canonical manifest or a generated surface
Manual dispatch with optional target version

Process:

Read Canonical Version - Reads dotfiles_version from .chezmoidata.toml
Sync Versions - Updates all markdown files with version references
Verify Consistency - Ensures all references match target version
Commit & Push - Automatically commits changes (except on PRs)

Features:

Backup creation before changes
Comprehensive change reporting
PR comment integration
Artifact preservation for rollback

2. Local Synchronization Script

Location: scripts/version-sync.sh

Usage:

# Sync to the canonical dotfiles_version
./scripts/version-sync.sh

# Sync to specific version
./scripts/version-sync.sh 1.2.3

# Preview changes without applying
./scripts/version-sync.sh --dry-run

# Verify current consistency
./scripts/version-sync.sh --verify

Options:

--dry-run - Preview changes without applying
--verify - Check version consistency only
--backup / --no-backup - Control backup creation
--force - Force sync even if no changes detected

3. Version Patterns

The system recognizes and updates these patterns:

README.md

[![Version](https://img.shields.io/badge/Version-v0.2.501-blue?style=for-the-badge)]

Documentation Files

**Version**: v0.2.503
**Dotfiles Version**: v0.2.503
Version: v0.2.503
version 0.2.485

Integration Points

CI/CD Pipeline Integration

The workflow integrates with the existing CI pipeline:

# Existing CI workflow can depend on version sync
needs: [sync-versions, lint-shell, test-linux]

Git Hooks Integration

For local development, add to .git/hooks/pre-commit:

#!/bin/bash
# Check version consistency before commits
./scripts/version-sync.sh --verify || {
    echo "Version inconsistency detected. Run: ./scripts/version-sync.sh"
    exit 1
}

Canonical Manifest Integration

Change the version explicitly through the synchronizer; it updates the canonical manifest and regenerates package.json in the same operation:

./scripts/version-sync.sh 0.2.522
./scripts/release-preflight --require-untagged

Workflow Examples

Scenario 1: Version Bump

# Developer updates the canonical manifest and all generated surfaces
./scripts/version-sync.sh 0.2.522

# Push to main
git push origin main

# GitHub Actions automatically:
# 1. Detects version change
# 2. Updates all markdown files
# 3. Commits and pushes changes
# 4. Verifies consistency

Scenario 2: PR Review

# PR with version-surface changes
# GitHub Actions automatically:
# 1. Checks version consistency
# 2. Reports any mismatches
# 3. Comments on PR with sync status
# 4. Provides diff preview

Scenario 3: Manual Sync

# Local development
./scripts/version-sync.sh --dry-run  # Preview changes
./scripts/version-sync.sh            # Apply changes
./scripts/version-sync.sh --verify   # Confirm consistency

File Detection Logic

Automatic Discovery

The system automatically discovers files containing version references:

rg -l "v?[0-9]+\.[0-9]+\.[0-9]+" --type md

Known Files

These files are always included even if they don't currently contain versions:

README.md
docs/reference/FEATURES.md
Any file matching version patterns

Exclusions

Files that are intentionally excluded:

CHANGELOG.md - May contain historical versions
package.json - Generated package-registry metadata
docs/security/COMPLIANCE.md - Includes external compliance spec versions
docs/reference/FONTS.md - Includes upstream font release versions
docs/archive/LEGACY_ROADMAP.md - Keeps historical release markers
docs/archive/PLAN.md - Captures multi-release planning references
docs/operations/VERSION_SYNC.md - Documentation examples and usage
docs/architecture/WALKTHROUGH.md - Contains environment-specific tag examples
docs/guides/WSL2_NIX_TROUBLESHOOTING.md - Contains IP addresses and version-like values
Binary files
Test fixtures

Error Handling

Common Issues

Version Mismatch

❌ Found inconsistent release in docs/reference/FEATURES.md: vX.Y.Z (expected: vA.B.C)

Solution: Run ./scripts/version-sync.sh to fix

Missing Dependencies

❌ jq is required but not installed

Solution: Install dependencies (jq, rg)

Permission Issues

❌ Permission denied writing to README.md

Solution: Check file permissions and Git status

Recovery Procedures

Rollback Changes

# Restore from backup
cp .version-sync-backup/README.md.*.backup README.md

# Or restore from Git
git checkout HEAD~1 -- README.md

Force Resync

./scripts/version-sync.sh --force

Monitoring & Maintenance

Health Checks

# Daily verification (add to cron)
./scripts/version-sync.sh --verify || echo "Version drift detected"

Metrics Tracking

The GitHub Actions workflow provides metrics:

Files scanned
Files updated
Verification status
Processing time

Backup Strategy

Local backups in .version-sync-backup/
GitHub Actions artifacts (30-day retention)
Git history for rollback

Security Considerations

Token Permissions

permissions:
  contents: write      # Required for commits
  pull-requests: write # Required for PR comments

Validation

Version format validation (x.y.z pattern)
File path validation (no directory traversal)
Change verification before commit

Audit Trail

All changes logged in Git history
GitHub Actions run history
Backup preservation

Performance Optimization

Caching Strategy

Git operations use shallow fetch when possible
Pattern compilation cached
File discovery optimized with ripgrep

Parallel Processing

File processing is sequential but optimized
Git operations batched
Verification runs concurrently with updates

Resource Usage

Typical run time: 30-60 seconds
Memory usage: <100MB
Network usage: Minimal (only Git operations)

Future Enhancements

Planned Features

Smart Version Detection - Semantic version awareness
Template Support - Custom version patterns
Multi-Format Support - YAML, JSON, TOML files
Rollback Automation - One-command rollback
Integration Testing - End-to-end workflow tests

Extension Points

Custom pattern definitions
File-specific update rules
Pre/post-sync hooks
External validation services

Troubleshooting

Debug Mode

# Enable verbose output
DEBUG=1 ./scripts/version-sync.sh --dry-run

Common Solutions

Issue	Solution
Script not executable	`chmod +x scripts/version-sync.sh`
Missing tools	`apt install jq ripgrep` (Ubuntu)
Permission denied	Check Git status and file permissions
Workflow not triggering	Verify the canonical manifest change is in the push
Changes not committed	Check branch protection rules

Log Analysis

# View GitHub Actions logs
gh run list --workflow=sync-versions.yml
gh run view <run-id> --log

Contributing

Testing Changes

# Test local changes
./scripts/version-sync.sh --dry-run

# Test workflow changes (requires GitHub CLI)
gh workflow run sync-versions.yml --ref feature-branch

Adding New Patterns

Update pattern regex in script
Add test cases
Update documentation
Submit PR with examples

Last Updated: 2026-02-15 Version: v0.2.503 Maintainer: Principal Automation Engineer Status: Production Ready ✅