feat: implement dynamic version management with git tags as single source of truth

- Remove obsolete version management files and documentation
- Update all scripts to use dynamic version resolution from git tags
- Implement robust fallback system for packaged environments
- Ensure version consistency across build tools and package
- Follow best practices: git tags → env → fallback → default
- Remove unnecessary documentation files per best practices

Author: yammanhammad

route_planner/__init__.py

@@ -6,7 +6,25 @@
 and comprehensive offline support.
 """
 
-__version__ = "1.1.11"
+def _get_version():
+    """Get version from git tags (single source of truth) or fallback."""
+    try:
+        import subprocess
+        from pathlib import Path
+        project_root = Path(__file__).parent.parent
+        result = subprocess.run(
+            ['git', 'describe', '--tags', '--abbrev=0'],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return result.stdout.strip().lstrip('v')
+    except (subprocess.CalledProcessError, FileNotFoundError, ImportError):
+        # Fallback for environments without git or in packaged distributions
+        return "1.1.11"
+
+__version__ = _get_version()
 __author__ = "Route Planner Development Team"
 
 # Ensure config is available at package level

scripts/README.md

@@ -11,7 +11,7 @@ This directory contains automation scripts that handle version management, envir
 ```bash
 # Version Management
 python scripts/version.py                    # Show current version
-python scripts/version.py --update 1.2.3    # Update package version to 1.2.3
+python scripts/version.py --update X.Y.Z    # Update package version to X.Y.Z (e.g., 1.2.3)
 
 # Environment & Development
 python scripts/setup_env.py                  # Setup development environment
@@ -97,10 +97,10 @@ route-planner                      # If installed globally
 python scripts/version.py
 
 # Update version for release
-python scripts/version.py --update 2.1.0
+python scripts/version.py --update X.Y.Z
 
 # Prepare release (updates changelog, creates tag)
-python scripts/prepare_release.py --version 2.1.0
+python scripts/prepare_release.py --version X.Y.Z
 ```
 
 ### 📦 Building Packages

scripts/build_appimage.py

@@ -56,9 +56,16 @@ def get_version():
             from scripts.version import get_version
             return get_version()
         except ImportError:
-            # Fallback to a default version
-            print("⚠️ Could not determine version, using 1.0.0")
-            return "1.0.0"
+            # Fallback: try to get version from git or use default
+            print("⚠️ Could not determine version from package, trying git...")
+            try:
+                import subprocess
+                result = subprocess.run(['git', 'describe', '--tags', '--abbrev=0'], 
+                                      capture_output=True, text=True, check=True)
+                return result.stdout.strip().lstrip('v')
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                print("⚠️ Git not available, using fallback version 1.0.0")
+                return "1.0.0"
 
 def build_appimage():
     """Build an AppImage package for Route Planner."""

scripts/build_flatpak.py

@@ -75,9 +75,16 @@ def get_version():
             from scripts.version import get_version
             return get_version()
         except ImportError:
-            # Fallback to a default version
-            print("⚠️ Could not determine version, using 1.0.0")
-            return "1.0.0"
+            # Fallback: try to get version from git or use default
+            print("⚠️ Could not determine version from package, trying git...")
+            try:
+                import subprocess
+                result = subprocess.run(['git', 'describe', '--tags', '--abbrev=0'], 
+                                      capture_output=True, text=True, check=True)
+                return result.stdout.strip().lstrip('v')
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                print("⚠️ Git not available, using fallback version 1.0.0")
+                return "1.0.0"
 
 def create_flatpak_manifest():
     """Create a Flatpak manifest for Route Planner."""

scripts/prepare_release.py

@@ -170,7 +170,7 @@ def add_release_notes_entry(version):
 def main():
     if len(sys.argv) != 2:
         print("Usage: python scripts/prepare_release.py <version>")
-        print("Example: python scripts/prepare_release.py 1.2.0")
+        print("Example: python scripts/prepare_release.py X.Y.Z (semantic versioning)")
         sys.exit(1)
 
     new_version = sys.argv[1]

scripts/version.py

@@ -41,49 +41,61 @@ def get_version_from_package():
         return None
 
 def get_version():
-    """Get current version. Priority: git -> package -> env -> default."""
-    # Try git first (for releases)
+    """Get current version. Priority: git tags -> env -> package -> default."""
+    # Priority 1: Git tags (single source of truth)
     version = get_version_from_git()
     if version:
         return version
 
-    # Try package version
-    version = get_version_from_package()
-    if version:
-        return version
-    
-    # Try environment (for CI)
+    # Priority 2: Environment (for CI overrides)
     version = os.getenv('VERSION')
     if version:
         return version.lstrip('v')
 
-    # Default fallback
+    # Priority 3: Package version (fallback for development)
+    version = get_version_from_package()
+    if version:
+        return version
+    
+    # Priority 4: Default fallback
     return "0.0.0"
 
 def update_package_version(new_version):
-    """Update version in __init__.py."""
+    """Update fallback version in __init__.py and create git tag."""
     if not INIT_FILE.exists():
         print(f"Error: {INIT_FILE} not found")
         return False
 
     try:
+        # Update the fallback version in the package
         with open(INIT_FILE, 'r', encoding='utf-8') as f:
             content = f.read()
 
+        # Update the fallback version in the _get_version function
         updated = re.sub(
-            r'__version__ = [\'"][^\'"]*[\'"]',
-            f'__version__ = "{new_version}"',
+            r'return "[\d\.]+"',
+            f'return "{new_version}"',
             content
         )
 
         if content != updated:
             with open(INIT_FILE, 'w', encoding='utf-8') as f:
                 f.write(updated)
-            print(f"Updated version to {new_version}")
-            return True
-        else:
-            print(f"Version already {new_version}")
+            print(f"Updated fallback version to {new_version}")
+        
+        # Create git tag (this becomes the real source of truth)
+        try:
+            import subprocess
+            subprocess.run(['git', 'tag', f'v{new_version}'], check=True)
+            print(f"Created git tag v{new_version}")
             return True
+        except subprocess.CalledProcessError as e:
+            if "already exists" in str(e):
+                print(f"Tag v{new_version} already exists")
+                return True
+            else:
+                print(f"Error creating git tag: {e}")
+                return False
 
     except Exception as e:
         print(f"Error updating version: {e}")