From a29ce72afcd2e6221199627e30451d1d16a08e1c Mon Sep 17 00:00:00 2001
From: Michael Chouinard <46358556+chouinar@users.noreply.github.com>
Date: Wed, 28 Aug 2024 11:37:42 -0400
Subject: [PATCH] Pin Python minor version and document upgrade details (#235)

## Changes

Pin the Python version and document details on how to upgrade

## Context for reviewers

Python releases new minor versions (3.12, 3.13, etc.) every year in
October. It usually takes a few weeks for all of our dependencies and
tooling to also be upgraded to the latest version, causing our builds to
break. There isn't much we can do except wait a few weeks and then do
the upgrade (assuming no breaking changes in features we use).

However, we had some of our dependencies pinned to the major version
(Python 3) so it has broken the past few years until it started working
again when the dependencies got fixed. This is just getting ahead of
that and making sure the upgrade to Python 3.13 doesn't cause any
problems.

## Testing
This change is largely documentation as the Python version used in the
dockerfile + pyproject.toml already would have resolved to Python 3.12,
this just makes it so it won't auto-upgrade to 3.13 when that releases
in October.
---
 app/Dockerfile     |  4 +++-
 app/poetry.lock    |  6 +++---
 app/pyproject.toml |  4 +++-
 docs/app/README.md | 27 +++++++++++++++++++++++++++
 4 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/app/Dockerfile b/app/Dockerfile
index fd017c5..66a3650 100644
--- a/app/Dockerfile
+++ b/app/Dockerfile
@@ -4,7 +4,9 @@
 # The build stage that will be used to deploy to the various environments
 # needs to be called `release` in order to integrate with the repo's
 # top-level Makefile
-FROM python:3-slim AS base
+FROM python:3.12-slim AS base
+# See /docs/app/README.md#Upgrading Python
+# for details on upgrading your Python version
 
 # Install poetry, the package manager.
 # https://python-poetry.org
diff --git a/app/poetry.lock b/app/poetry.lock
index c5b0b70..e51bc8e 100644
--- a/app/poetry.lock
+++ b/app/poetry.lock
@@ -949,7 +949,7 @@ files = [
 
 [package.dependencies]
 marshmallow = [
-    {version = ">=3.13.0,<4.0", optional = true, markers = "python_version < \"3.7\" or extra != \"enum\""},
+    {version = ">=3.13.0,<4.0"},
     {version = ">=3.18.0,<4.0", optional = true, markers = "python_version >= \"3.7\" and extra == \"enum\""},
 ]
 typeguard = {version = ">=2.4.1,<4.0.0", optional = true, markers = "extra == \"union\""}
@@ -1981,5 +1981,5 @@ files = [
 
 [metadata]
 lock-version = "2.0"
-python-versions = "^3.12"
-content-hash = "259e2bd37870236ef86dc5893950acf19912b7468e906dc61f78436ea5f34796"
+python-versions = "~3.12"
+content-hash = "885d91299426a19ef533e20f8d85a652c639eb031091bbb9501da467c374e873"
diff --git a/app/pyproject.toml b/app/pyproject.toml
index 497aae2..977ecd5 100644
--- a/app/pyproject.toml
+++ b/app/pyproject.toml
@@ -6,7 +6,9 @@ packages = [{ include = "src" }]
 authors = ["Nava Engineering <engineering@navapbc.com>"]
 
 [tool.poetry.dependencies]
-python = "^3.12"
+# See /docs/app/README.md#Upgrading Python
+# for details on upgrading your Python version
+python = "~3.12"
 SQLAlchemy = {version = "^2.0.21", extras = ["mypy"]}
 alembic = "^1.12.0"
 python-dotenv = "^1.0.0"
diff --git a/docs/app/README.md b/docs/app/README.md
index 52bd454..05a80ff 100644
--- a/docs/app/README.md
+++ b/docs/app/README.md
@@ -152,3 +152,30 @@ The API can be run in debug mode that allows for remote attach debugging (curren
     ]
 }
 ```
+
+## Upgrading Python
+Python does [yearly releases](https://devguide.python.org/versions/) for their minor versions (eg. 3.12 -> 3.13). They do not
+use semvar versioning, and their [minor releases](https://devguide.python.org/developer-workflow/development-cycle/#devcycle) contain
+breaking changes.
+
+Pin to a specific minor version of python just in case anything would break when the yearly release does occur.
+Only pin the minor versions of Python (eg. 3.12), and not the patch versions (eg. 3.12.1) as those contain bug and security fixes.
+
+Along with any version upgrades, remember to:
+- Test the system functionality before deploying to production
+- Review the [changelog](https://docs.python.org/3/whatsnew/changelog.html)
+for any breaking changes of features you may use
+
+### Upgrade Steps
+To upgrade the Python version, make changes in the following places:
+1. Local Python version (see more about managing local Python versions in [getting started](/docs/app/getting-started.md))
+2. [Dockerfile](/app/Dockerfile)
+    search for the line `FROM python:3.12-slim as base` - supported versions can be found on [Dockerhub](https://hub.docker.com/_/python)
+3. [pyproject.toml](/app/pyproject.toml)
+    search for the line
+    ```toml
+    [tool.poetry.dependencies]
+    python = "~3.12"
+    ```
+   Then run `poetry lock --no-update` to update the [poetry.lock](/app/poetry.lock) file.
+4. [.python-version](/app/.python-version) which is used by tools like pyenv