feat: implement semantic versioning with setuptools-scm

- Configure setuptools-scm in pyproject.toml for dynamic versioning
- Add /api/version endpoint in Flask backend
- Create useVersion hook and display version in frontend sidebar
- Update README files with tagging workflow documentation
- Remove hardcoded version in favor of Git tag-based versioning

Resolves #175

Co-authored-by: yangm2 <[email protected]>

Author: claude[bot]

README.md

@@ -89,6 +89,40 @@ Live at https://tenantfirstaid.com/
     ```
     `--keep-going` will continue to run checks, even if previous `make` rule fail.  Omit if you want to stop after the first `make` rule fails.
 
+## Versioning and Releases
+
+This project uses [semantic versioning](https://semver.org/) with automated version management via `setuptools-scm`. The version is automatically derived from Git tags.
+
+### Creating a Release
+
+1. **Determine the version bump type:**
+   - **Patch release** (0.2.0 → 0.2.1): Bug fixes, minor improvements
+   - **Minor release** (0.2.0 → 0.3.0): New features, backward-compatible changes
+   - **Major release** (0.2.0 → 1.0.0): Breaking changes
+
+2. **Create and push a tag:**
+   ```bash
+   # For a patch release (default for regular PRs)
+   git tag v0.2.1
+   git push origin v0.2.1
+   
+   # For a minor release (feature additions)
+   git tag v0.3.0
+   git push origin v0.3.0
+   
+   # For a major release (breaking changes)
+   git tag v1.0.0
+   git push origin v1.0.0
+   ```
+
+3. **The version will automatically be updated** in the backend API and displayed in the frontend UI.
+
+### Checking the Current Version
+
+- **Backend API**: Visit `/api/version` endpoint
+- **Frontend UI**: Check the sidebar navigation (bottom)
+- **Command line**: Run `uv run python -c "from importlib.metadata import version; print(version('tenant-first-aid'))"`
+
 ## Contributing
 
 We currently have regular project meetups: https://www.meetup.com/codepdx/ . Also check out https://www.codepdx.org/ to find our Discord server.

backend/README.md

@@ -0,0 +1,64 @@
+# Tenant First Aid Backend
+
+Flask backend API for the Tenant First Aid chatbot.
+
+## Development Setup
+
+See the main [README.md](../README.md) for full setup instructions.
+
+## API Endpoints
+
+- `/api/init` - Initialize chat session
+- `/api/query` - Send chat message
+- `/api/history` - Get chat history
+- `/api/clear-session` - Clear current session
+- `/api/citation` - Get citation information
+- `/api/version` - Get application version
+
+## Version Management
+
+This backend uses `setuptools-scm` for automatic version management based on Git tags. The version is dynamically generated from the repository's tag history.
+
+### Checking Version
+
+```bash
+# In the backend directory
+uv run python -c "from importlib.metadata import version; print(version('tenant-first-aid'))"
+
+# Or via the API
+curl http://localhost:5001/api/version
+```
+
+### Creating a New Release
+
+1. Ensure all changes are committed and pushed
+2. Create a new tag following semantic versioning:
+   ```bash
+   git tag v0.3.0  # or appropriate version
+   git push origin v0.3.0
+   ```
+3. The version will automatically be updated in the application
+
+## Development Commands
+
+From the `backend/` directory:
+
+```bash
+# Install dependencies
+uv sync
+
+# Run the server
+uv run python -m tenantfirstaid.app
+
+# Run tests
+uv run pytest
+
+# Format code
+uv run ruff format
+
+# Lint code
+uv run ruff check
+
+# Type check
+uv run ty check
+```

backend/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tenant-first-aid"
-version = "0.2.0"
+dynamic = ["version"]
 requires-python = ">=3.12"
 dependencies = [
   "flask>=3.1.1",
@@ -15,16 +15,21 @@ dependencies = [
   "python-dotenv",
   "pandas>=2.3.0",
   "vertexai>=1.43.0",
+  "setuptools-scm>=8",
 ]
 
 [tool.setuptools.packages.find]
 where = ["."]
 exclude = ["data*"]
 
 [build-system]
-requires = ["setuptools>=61"]
+requires = ["setuptools>=61", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
+[tool.setuptools_scm]
+version_scheme = "guess-next-dev"
+local_scheme = "no-local-version"
+
 [dependency-groups]
 dev = [
     "ipdb>=0.13.13",

backend/tenantfirstaid/app.py

@@ -3,6 +3,11 @@
 import os
 import secrets
 
+try:
+    from importlib.metadata import version
+except ImportError:
+    from importlib_metadata import version
+
 
 if Path(".env").exists():
     from dotenv import load_dotenv
@@ -38,6 +43,16 @@ def clear_session():
     return jsonify({"success": True})
 
 
+@app.get("/api/version")
+def get_version():
+    try:
+        app_version = version("tenant-first-aid")
+        return jsonify({"version": app_version})
+    except Exception as e:
+        # Fallback if setuptools-scm isn't working or in development
+        return jsonify({"version": "development", "error": str(e)})
+
+
 app.add_url_rule(
     "/api/init",
     view_func=InitSessionView.as_view("init", tenant_session),

frontend/README.md

@@ -0,0 +1,73 @@
+# Tenant First Aid Frontend
+
+React frontend application for the Tenant First Aid chatbot.
+
+## Development Setup
+
+See the main [README.md](../README.md) for full setup instructions.
+
+## Version Display
+
+The application version is automatically fetched from the backend API and displayed in the navigation sidebar. The version corresponds to the backend version derived from Git tags.
+
+### Version Hook
+
+The frontend includes a custom `useVersion` hook that fetches version information from `/api/version`:
+
+```typescript
+import { useVersion } from "./hooks/useVersion";
+
+function MyComponent() {
+  const { version, loading, error } = useVersion();
+  
+  return (
+    <div>
+      {loading ? "Loading..." : error ? "Version unavailable" : `v${version}`}
+    </div>
+  );
+}
+```
+
+## Development Commands
+
+From the `frontend/` directory:
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+
+# Preview production build
+npm run preview
+```
+
+## Creating a New Release
+
+The frontend version automatically reflects the backend version. To create a new release:
+
+1. Ensure all changes are committed and pushed to the main branch
+2. Create and push a new Git tag:
+   ```bash
+   git tag v0.3.0  # Follow semantic versioning
+   git push origin v0.3.0
+   ```
+3. The version will automatically be updated and displayed in the UI
+
+## Architecture
+
+- **React 19** with TypeScript
+- **Vite** for build tooling and development server
+- **Tailwind CSS** for styling
+- **React Router** for navigation
+- **TanStack Query** for API state management

frontend/src/hooks/useVersion.tsx

@@ -0,0 +1,35 @@
+import { useState, useEffect } from "react";
+
+interface VersionResponse {
+  version: string;
+  error?: string;
+}
+
+export function useVersion() {
+  const [version, setVersion] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const fetchVersion = async () => {
+      try {
+        const response = await fetch("/api/version");
+        const data: VersionResponse = await response.json();
+        
+        if (response.ok) {
+          setVersion(data.version);
+        } else {
+          setError("Failed to fetch version");
+        }
+      } catch (err) {
+        setError("Failed to fetch version");
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchVersion();
+  }, []);
+
+  return { version, loading, error };
+}

frontend/src/pages/Chat/components/Navbar.tsx

@@ -1,9 +1,11 @@
 import { useState } from "react";
 import { Link } from "react-router-dom";
 import TenantFirstAidLogo from "../../../shared/components/TenatFirstAidLogo";
+import { useVersion } from "../../../hooks/useVersion";
 
 export default function Navbar() {
   const [sidebarOpen, setSidebarOpen] = useState(false);
+  const { version, loading, error } = useVersion();
 
   return (
     <nav className="fixed top-0 left-0 w-full bg-[#1F584F] shadow-md py-3 px-6 z-50">
@@ -44,7 +46,7 @@ export default function Navbar() {
           sidebarOpen ? "translate-x-0" : "translate-x-full"
         }`}
       >
-        <div className="flex flex-col p-8 gap-6 mt-10">
+        <div className="flex flex-col h-full p-8 gap-6 mt-10">
           <Link
             to="/"
             className="block px-3 py-2 rounded text-gray-700 font-medium transition-colors hover:bg-[#4F8B82] hover:text-[#F4F4F2]"
@@ -74,6 +76,17 @@ export default function Navbar() {
             Privacy Policy
           </Link>
           <hr className="my-2 border-t border-gray-300" />
+          <div className="mt-auto pb-4">
+            <div className="text-xs text-gray-500 text-center">
+              {loading ? (
+                "Loading version..."
+              ) : error ? (
+                "Version unavailable"
+              ) : (
+                `v${version}`
+              )}
+            </div>
+          </div>
         </div>
       </div>