Git Version Tagging Guide

This document outlines the process for managing version tags in the project's Git repository.

Version Tagging Conventions

The project follows these versioning conventions:

Production releases: v0.0.X (e.g., v0.0.35)
Development releases: v0.0.X-dev1 (e.g., v0.0.34-dev1)
Format follows a modified semantic versioning pattern

Incrementing Version Tags

Follow these steps to increment the version tag for a new release:

1. Check Existing Tags

List all existing version tags to understand the current versioning state:

git tag -l "v*"

2. Find the Latest Version Tag

For Windows PowerShell, use these commands to find the latest tags:

# Find latest production tag (frank)
git tag -l "v0.0.*-frank" | Sort-Object -Property @{Expression={[int]($_ -replace '^v0.0.', '' -replace '-frank$', '')}; Descending=$true} | Select-Object -First 1

# Find latest development tag (dev)
git tag -l "v0.0.*-dev*" | Sort-Object -Property @{Expression={[int]($_ -replace '^v0.0.', '' -replace '-dev.*$', '')}; Descending=$true} | Select-Object -First 1

For Linux/macOS bash, use these commands:

# Find latest production tag (frank)
git tag -l "v0.0.*-frank" | sort -V | tail -1

# Find latest development tag (dev)
git tag -l "v0.0.*-dev*" | sort -V | tail -1

3. Increment the Version Number

Based on the latest tag, increment the version number according to the project's versioning scheme:

If the latest tag is v0.0.34-frank, the new tag would be v0.0.35-frank
For development versions, increment the version number only (e.g., v0.0.34-dev1 → v0.0.35-dev1)
Important: "dev1" is the channel identifier and remains constant; only increment the version number
Example: v0.0.87-dev1 → v0.0.88-dev1 (correct)
Example: v0.0.87-dev1 → v0.0.87-dev2 (incorrect)

4. Create a New Annotated Tag

Create a new annotated tag with a descriptive message:

git tag -a v0.0.35-frank -m "Description of changes in this version"

5. Push the New Tag to the Remote Repository

Push the new tag to the remote repository:

git push origin v0.0.35-frank

Best Practices

Use Annotated Tags: Always use annotated tags (-a flag) for releases, as they contain metadata including the tagger's name, email, date, and a message.
Descriptive Messages: Include a concise but descriptive message that summarizes the key changes in this version.
Consistent Naming: Follow the established naming convention consistently.
Tag After Testing: Create and push tags only after the code has been tested and confirmed to be working correctly.
Don't Reuse Tags: Never reuse or move existing tags. If a mistake is made, delete the tag and create a new one.

Deleting Tags (If Necessary)

If you need to delete a tag (e.g., if it was created incorrectly):

# Delete local tag
git tag -d v0.0.35-frank

# Delete remote tag
git push origin :refs/tags/v0.0.35-frank

End of VERSION_TAGGING.md

3.0 KiB Raw Blame History