From 4a37a47887ffb5a54cc874e4f99816d7bc21c51d Mon Sep 17 00:00:00 2001 From: Michael Chihlas Date: Thu, 7 May 2026 11:31:28 -0400 Subject: [PATCH] chore(env): standardize backend python on 3.12 Co-Authored-By: Codex --- .ai/DECISIONS.md | 10 ++++++++++ .ai/HANDOFF.md | 4 ++-- .ai/PROJECT_CONTEXT.md | 2 +- .ai/SESSION_LOG.md | 8 ++++++++ .gitea/workflows/ci.yml | 10 ++++++++++ .github/workflows/ci.yml | 8 ++++---- .python-version | 1 + DEV-ENV.md | 4 ++-- README.md | 2 +- 9 files changed, 39 insertions(+), 10 deletions(-) create mode 100644 .python-version diff --git a/.ai/DECISIONS.md b/.ai/DECISIONS.md index 9400fad6..df018ccb 100644 --- a/.ai/DECISIONS.md +++ b/.ai/DECISIONS.md @@ -13,6 +13,16 @@ --- +## 2026-05-07 — Standardize backend Python on 3.12 + +**Context:** Runtime facts had drifted from docs. The backend Dockerfiles and running dev container were already on Python 3.12, GitHub CI had just been updated to 3.12, but project docs still said Python 3.11 and Gitea CI relied on the runner's ambient Python. + +**Decision:** Treat Python 3.12 as the backend standard. Pin local pyenv via `.python-version` to 3.12.13, matching the current `python:3.12-slim` container patch level. Add explicit Python 3.12 setup to Gitea CI and keep GitHub CI on Python 3.12. + +**Rejected:** Moving Docker/runtime back to Python 3.11. The application was already building and running on 3.12, so reverting the runtime would add churn without a product or dependency reason. + +**Consequences:** Native backend work should use `backend/venv` created from Python 3.12.13. Future docs/CI/runtime changes should preserve Python 3.12 unless a deliberate upgrade decision is recorded. + ## 2026-04-30 — Add `applied_pending` non-terminal status to suggested fixes **Context:** The verifying banner forces a synchronous verdict — worked / didn't / partial — but a lot of real MSP fixes are async. Engineer ran the script but is waiting on the client to power-cycle, AD replication, an O365 license sync. With only the existing outcomes, the engineer either leaves the banner stale (eroding the verifying signal) or guesses wrong (corrupting outcome data). User flagged the gap directly. Today's `NudgeBanner` "Still checking" button just silences the nudge — it doesn't tell the system anything. diff --git a/.ai/HANDOFF.md b/.ai/HANDOFF.md index f3e5ea51..b451d845 100644 --- a/.ai/HANDOFF.md +++ b/.ai/HANDOFF.md @@ -2,7 +2,7 @@ # HANDOFF.md -**Last updated:** 2026-05-07 (native Python environment rechecked; cutover ops still pending) +**Last updated:** 2026-05-07 (Python 3.12 standardization applied; cutover ops still pending) **Active task:** None mid-flight. Branch `feat/self-serve-signup-phase-2` (HEAD `502c0a4`) is ready to PR. @@ -63,7 +63,7 @@ New env vars (Vite ARG/ENV in Dockerfile + `.env.example`): `VITE_SELF_SERVE_ENA ## Environment notes (carry-forward) -- Code-server LXC now has native `python`/`python3` via pyenv at Python 3.12.10, plus `pip` 25.0.1. There is no native `python3.11`, no repo virtualenv, and the native environment has only pip installed (`python -m pytest --version` fails with `No module named pytest`). Backend remains documented for Python 3.11, so use Docker for authoritative backend validation until a 3.11 env is installed. +- Code-server LXC now standardizes on Python 3.12. `.python-version` pins 3.12.13 to match the Docker image; native backend work should use `backend/venv` built from that interpreter. `pytest --version` and `alembic --version` pass natively when `DEBUG=true SECRET_KEY=ci-test-secret-key-not-for-production` are supplied to avoid local `.env` validation failures. - Pytest: `docker exec resolutionflow_backend pytest tests/ -v --override-ini="addopts="`. - Vitest: `docker exec -w /app resolutionflow_frontend npm test -- --run`. - TS build: `docker exec -w /app resolutionflow_frontend npx tsc -b`. diff --git a/.ai/PROJECT_CONTEXT.md b/.ai/PROJECT_CONTEXT.md index 0694c480..26b9801f 100644 --- a/.ai/PROJECT_CONTEXT.md +++ b/.ai/PROJECT_CONTEXT.md @@ -26,7 +26,7 @@ Go-to-Market Validation (pre-PMF). Backend feature-complete (55+ endpoints, 100+ ## Tech stack -- **Backend:** Python 3.11 + FastAPI, SQLAlchemy 2.0 async (asyncpg), Alembic, Pydantic v2, JWT (python-jose + bcrypt, JTI refresh rotation), APScheduler (in-process with FastAPI lifespan). +- **Backend:** Python 3.12 + FastAPI, SQLAlchemy 2.0 async (asyncpg), Alembic, Pydantic v2, JWT (python-jose + bcrypt, JTI refresh rotation), APScheduler (in-process with FastAPI lifespan). - **Frontend:** React 19 + Vite + TypeScript, Tailwind v4 (CSS-only config in `index.css`), Zustand (immer + zundo), React Router v7, Axios (token-refresh interceptor), Lucide. - **DB:** PostgreSQL 16 (RLS enabled Phase 4, pgvector). diff --git a/.ai/SESSION_LOG.md b/.ai/SESSION_LOG.md index 123ece7f..177e8430 100644 --- a/.ai/SESSION_LOG.md +++ b/.ai/SESSION_LOG.md @@ -12,6 +12,14 @@ --- +## 2026-05-07 11:30 EDT — Codex — Standardize backend Python on 3.12 + +- Standardized repo declarations around Python 3.12: added `.python-version` pinned to 3.12.13, updated stale Python 3.11 docs, and added explicit Python 3.12 setup steps to Gitea CI. GitHub CI was already updated to Python 3.12 by the user. +- Installed pyenv Python 3.12.13 and created `backend/venv` from that interpreter. Installed `backend/requirements-dev.txt` into the venv. +- Verified native `python --version` and venv `python --version` both report 3.12.13. Verified native `pytest 8.4.2` and `alembic 1.18.3` with explicit safe test env vars; plain pytest import still depends on local `.env` values being valid. +- Rebuilt and restarted the dev backend container with `docker compose -f docker-compose.dev.yml build backend` and `up -d backend`; confirmed `docker exec resolutionflow_backend python --version` reports 3.12.13. +- Files touched: `.python-version`, `.gitea/workflows/ci.yml`, `.github/workflows/ci.yml`, `README.md`, `DEV-ENV.md`, `.ai/PROJECT_CONTEXT.md`, `.ai/DECISIONS.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`. + ## 2026-05-07 11:14 EDT — Codex — Recheck native Python availability - Re-ran the startup ritual and checked the host Python state after the user reported fixing the missing native Python issue. diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index d87bdacc..079eb83a 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -46,6 +46,11 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: "3.12" + - name: Cache pip uses: actions/cache@v3 with: @@ -171,6 +176,11 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: "3.12" + - name: Cache pip uses: actions/cache@v3 with: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 37f62d1f..2dc50cbb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,10 +37,10 @@ jobs: steps: - uses: actions/checkout@v5 - - name: Set up Python 3.11 + - name: Set up Python 3.12 uses: actions/setup-python@v5 with: - python-version: "3.11" + python-version: "3.12" cache: pip cache-dependency-path: | backend/requirements.txt @@ -143,10 +143,10 @@ jobs: steps: - uses: actions/checkout@v5 - - name: Set up Python 3.11 + - name: Set up Python 3.12 uses: actions/setup-python@v5 with: - python-version: "3.11" + python-version: "3.12" cache: pip cache-dependency-path: | backend/requirements.txt diff --git a/.python-version b/.python-version new file mode 100644 index 00000000..28d9a01b --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.12.13 diff --git a/DEV-ENV.md b/DEV-ENV.md index 1a166c1a..7bcc535f 100644 --- a/DEV-ENV.md +++ b/DEV-ENV.md @@ -108,7 +108,7 @@ Run these in order. Stop at the first failure and investigate. # Ubuntu / Debian sudo apt update && sudo apt install -y \ git curl build-essential \ - python3.11 python3.11-venv python3-pip \ + python3.12 python3.12-venv python3-pip \ postgresql-client # not the server — only if running Postgres natively # Node 20 via nvm (survives container rebuilds if stored in a volume) @@ -236,7 +236,7 @@ REPO_ROOT=/absolute/path/to/resolutionflow ```bash cd backend -python3.11 -m venv venv +python3.12 -m venv venv source venv/bin/activate pip install -r requirements.txt diff --git a/README.md b/README.md index 482f49ef..80f38eff 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ ## Quick Start ```bash -# Prerequisites: Docker, Python 3.11+, Node.js 20+ +# Prerequisites: Docker, Python 3.12, Node.js 20+ # Start PostgreSQL docker start patherly_postgres