# 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:

```powershell
git tag -l "v*"
```

### 2. Find the Latest Version Tag

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

```powershell
# 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:

```bash
# 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:

```powershell
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:

```powershell
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):

```powershell
# 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_