[MAINTENANCE] Design milestones and associate with release version numbers

[yunlishao]

Overview

Design and implement a milestone-based version management system that syncs with git tags and GitHub Releases.

Context

• Currently using manual version tracking in CommonLib/RealSimVersion.h
• TrafficLayer.exe displays version on startup (see TrafficLayer/TrafficLayer/mainTrafficLayer.cpp:81)
• Want to tie versions to GitHub milestones and releases
• Build process uses Visual Studio only (no CMake automation yet)

Version Strategy

Version Format: MAJOR.MINOR.PATCH (e.g., 0.6.12)

• MAJOR.MINOR: Controlled by GitHub milestones (e.g., milestone "v0.7" → versions 0.7.x)
• PATCH: Manually specified for bug fixes and small releases within a milestone
• No automatic versioning based on commit count

Example:

• Milestone "v0.6 - Basic Traffic Control" → releases: v0.6.0, v0.6.1, v0.6.12
• Milestone "v0.7 - Multi-Threading Support" → releases: v0.7.0, v0.7.1, etc.
• Milestone "v1.0 - Production Ready" → releases: v1.0.0, v1.0.1, etc.

Workflow

1. Create Milestones in GitHub

# Example milestone structure:
Milestone: "v0.7 - Multi-Threading Support"
├─ Issues: Link all relevant issues
├─ Due date: Target completion date
└─ Description: Feature summary

Milestone: "v1.0 - Production Ready"
├─ Issues: Production-critical features
└─ Due date: Release target

2. Work on Issues

• Assign issues to appropriate milestone
• Close issues as they are completed
• Monitor milestone progress (X/Y issues closed)

3. When Milestone Complete (Manual Process)

# Check no open issues remain
gh issue list --milestone "v0.7" --state open

# Tag the release
git tag v0.7.0 -m "Milestone: Multi-Threading Support complete"
git push origin v0.7.0

# Create GitHub Release from tag
gh release create v0.7.0 --title "v0.7.0 - Multi-Threading Support" --generate-notes

4. For Patch Releases (Between Milestones)

# After bug fixes, increment PATCH
git tag v0.7.1 -m "Bug fixes for v0.7"
git push origin v0.7.1
gh release create v0.7.1 --title "v0.7.1 - Bug fixes" --generate-notes

Technical Implementation Tasks

Phase 1: Auto-Generate Version Header (Required for Visual Studio)

• Create CommonLib/RealSimVersion.h.in template with placeholders
• Create PowerShell/batch script scripts/generate_version.bat that:
  • Runs git describe --tags to get latest tag
  • Parses tag into MAJOR, MINOR, PATCH
  • Generates RealSimVersion.h from template
  • Falls back to 0.0.0-unknown if no tags exist
• Add Pre-Build Event to TrafficLayer/TrafficLayer/TrafficLayer.vcxproj:

  <PreBuildEvent>
    <Command>call "$(SolutionDir)..\scripts\generate_version.bat"</Command>
  </PreBuildEvent>

• Update .gitignore to ignore generated CommonLib/RealSimVersion.h
• Test build process in Visual Studio

Phase 2: Initial Milestone Setup

• Tag current state as v0.6.0:

  git tag v0.6.0 -m "Current stable baseline"
  git push origin v0.6.0

• Create GitHub milestones for planned versions:
  • v0.7 - [Brief description of focus]
  • v0.8 - [Brief description of focus]
  • v1.0 - Production Ready
• Assign existing issues to appropriate milestones
• Set due dates for milestones

Phase 3: Documentation

• Create RELEASING.md documenting the release process
• Update README.md with version badge from latest release
• Document how to check version: Run TrafficLayer.exe --version or check startup output

Notes for Implementation

Current Files:

• CommonLib/RealSimVersion.h - Currently manual, will become auto-generated
• TrafficLayer/TrafficLayer/mainTrafficLayer.cpp:81 - Displays version using REALSIM_VERSION_STRING

Git Tag Format:

• Always use vX.Y.Z format (e.g., v0.6.12, v1.0.0)
• Annotated tags preferred: git tag -a v0.7.0 -m "message"

GitHub Release Management:

• Can mark releases as "pre-release" to hide from main view
• Can delete releases (keeps the tag)
• Use --generate-notes to auto-create changelog from commits

Future CI/CD Integration:

• When CI/CD is added, can automate release creation on tag push
• Can add automated testing before allowing tag/release
• Version generation script already CI-ready

Success Criteria

• TrafficLayer.exe displays correct version matching git tag
• No manual editing of version numbers in code
• Clear milestone → version mapping in GitHub
• Documented release process that any contributor can follow

Related Issues

• clean up #7 - Clean up (parent tracking issue)

[yunlishao]

This issue has been fully resolved:

Implementation:

• PR #7/automatic version management #68 implemented the automatic version management system (merged commit f92e045)
• scripts/generate_version.ps1 auto-generates RealSimVersion.h from git tags during build
• Pre-Build Event configured in TrafficLayer.vcxproj for all configurations

Milestones:

• Active milestones: 0.7.1, 0.7.2, 0.8.0, 0.9.0
• Git tags: v0.6.0, v0.7.0

All tasks from Phase 1-3 are complete. Closing this issue.