Merge pull request #167 from strick-j/develop

Merge develop into main

Author: strick-j

CLAUDE.md

@@ -273,7 +273,7 @@ lab-visualizer/
 │
 ├── docker-compose.yml         # Local development setup
 ├── Makefile                   # Task automation
-├── VERSION                    # Application version (e.g. 1.4.0)
+├── VERSION                    # Application version (e.g. 1.5.0)
 ├── README.md                  # User documentation
 ├── CLAUDE.md                  # This file (AI assistant context)
 ├── CONTRIBUTING.md            # Contributing guidelines
@@ -549,6 +549,11 @@ See `.env.example` for complete list. Key variables:
 - **Before every commit**, run `cd frontend && npx vitest run` and ensure all tests pass. Do not commit if any tests fail
 - **Before every commit**, run `cd frontend && npx tsc --noEmit` and ensure there are no TypeScript errors
 
+### Pre-Merge Checklist (main)
+- **Before merging to `main`**, verify that `VERSION` (root) and `frontend/package.json` `"version"` values match
+- **Before merging to `main`**, verify the version has been bumped appropriately for the scope of changes (MAJOR / MINOR / PATCH per SemVer)
+- The backend (`backend/app/version.py`) reads the `VERSION` file dynamically — it does not need a manual update
+
 ### Security Considerations
 - Never commit secrets or credentials
 - AWS credentials via IAM roles in production

CONTRIBUTING.md

@@ -34,10 +34,11 @@ This project follows [Semantic Versioning](https://semver.org/) (SemVer) with th
 
 Version numbers are maintained in the following locations and must be kept in sync:
 
-| File | Field |
-|------|-------|
-| `frontend/package.json` | `"version"` |
-| `backend/app/main.py` | `version` parameter in FastAPI app initialization |
+| File | Field | Notes |
+|------|-------|-------|
+| `VERSION` (root) | Plain text version string | **Source of truth** — read by backend and CI |
+| `frontend/package.json` | `"version"` | Must be updated manually to match `VERSION` |
+| `backend/app/main.py` | `version` parameter in FastAPI app | Reads from `VERSION` via `version.py` — no manual update needed |
 
 ### Release Process
 
@@ -46,6 +47,14 @@ Version numbers are maintained in the following locations and must be kept in sy
 3. Releases are tagged on `main` using the format `vMAJOR.MINOR.PATCH` (e.g., `v1.1.0`).
 4. Docker images are tagged automatically by CI using the git commit SHA and branch metadata. The `latest` tag is applied to builds from the `main` branch.
 
+### Pre-Merge Checklist
+
+Before merging to `main`, verify:
+
+- [ ] `VERSION` and `frontend/package.json` `"version"` values match
+- [ ] Version has been bumped appropriately for the scope of changes (MAJOR / MINOR / PATCH per SemVer)
+- [ ] All CI checks pass (lint, type-check, tests, security scans)
+
 ### Support Policy
 
 Only the latest released version receives security updates and bug fixes. See [SECURITY.md](SECURITY.md) for details on reporting vulnerabilities.

README.md

@@ -497,6 +497,12 @@ terraform apply
 
 See [infrastructure/README.md](infrastructure/README.md) for detailed deployment instructions.
 
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PATCH). The `VERSION` file in the repository root is the source of truth — the backend reads it dynamically via `backend/app/version.py`, and CI uses it for image tagging. The `frontend/package.json` `"version"` field must be kept in sync manually.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full release process and pre-merge checklist.
+
 ## Required Permissions
 
 ### AWS IAM Permissions

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aws-infra-visualizer-frontend",
   "private": true,
-  "version": "1.4.1",
+  "version": "1.5.0",
   "type": "module",
   "scripts": {
     "dev": "vite",