Charon/.github/skills/utility-version-check.SKILL.md

name, version, description, author, license, tags, compatibility, requirements, environment_variables, parameters, outputs, metadata

name	version	description	author	license	tags	compatibility	requirements	environment_variables	parameters	outputs	metadata
utility-version-check	1.0.0	Validates that VERSION.md/version file matches the latest git tag for release consistency	Charon Project	MIT	utility versioning validation git	os shells linux darwin bash	name version optional git >=2.0 false			name type description exit_code integer 0 if version matches, 1 if mismatch or error	category subcategory execution_time risk_level ci_cd_safe requires_network idempotent utility versioning short low true false true

Utility: Version Check

Overview

Validates that the version specified in .version file matches the latest git tag. This ensures version consistency across the codebase and prevents version drift during releases. The check is used in CI/CD to enforce version tagging discipline.

Prerequisites

• Git repository with tags
• .version file in repository root (optional)

Usage

Basic Usage

.github/skills/utility-version-check-scripts/run.sh

Via Skill Runner

.github/skills/scripts/skill-runner.sh utility-version-check

Via VS Code Task

Use the task: Utility: Check Version Match Tag

Parameters

This skill accepts no parameters.

Environment Variables

This skill requires no environment variables.

Outputs

• Success Exit Code: 0 - Version matches latest tag or no tags exist
• Error Exit Codes: 1 - Version mismatch detected
• Console Output: Validation result message

Success Output Example

OK: .version matches latest Git tag v0.3.0-beta.2

Error Output Example

ERROR: .version (0.3.0-beta.3) does not match latest Git tag (v0.3.0-beta.2)
To sync, either update .version or tag with 'v0.3.0-beta.3'

Examples

Example 1: Check Version During Release

# Before tagging a new release
.github/skills/utility-version-check-scripts/run.sh

Example 2: CI/CD Integration

- name: Validate Version
  run: .github/skills/scripts/skill-runner.sh utility-version-check

Version Normalization

The skill normalizes both the .version file content and git tag by:

• Stripping leading v prefix (e.g., v1.0.0 → 1.0.0)
• Removing newline and carriage return characters
• Comparing normalized versions

This allows flexibility in tagging conventions while ensuring consistency.

Error Handling

• No .version file: Exits with 0 (skip check)
• No git tags: Exits with 0 (skip check, allows commits before first tag)
• Version mismatch: Exits with 1 and provides guidance
• Git errors: Script fails with appropriate error message

Related Skills

• utility-bump-beta - Increment beta version
• build-check-go - Verify Go build integrity

Notes

• This check is non-blocking when no tags exist (allows initial development)
• Version format is flexible (supports semver, beta, alpha suffixes)
• Used in CI/CD to prevent merging PRs with version mismatches
• Part of the release automation workflow

---

Last Updated: 2025-12-20 Maintained by: Charon Project Source: scripts/check-version-match-tag.sh