Pin Python minor version and document upgrade details

Author: chouinar

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

app/poetry.lock

@@ -6,7 +6,9 @@ packages = [{ include = "src" }]
 authors = ["Nava Engineering <[email protected]>"]
 
 [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"

app/pyproject.toml

@@ -152,3 +152,60 @@ 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.
+
+We have this environment configured to use a specific minor version of python just in case anything would break when the yearly release does occur.
+
+We recommend as a starting point, 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.
+However, your project may have dependencies, or tools that rely on very specific patch versions of Python, so adjust your approach as necessary.
+
+Along with any version upgrades, you should follow all best practices for upgrading software and test the functionality
+of your system before deploying to production. It is also recommended to review the [changelog](https://docs.python.org/3/whatsnew/changelog.html)
+for any breaking changes of features you may use.
+
+## Local Development
+If you run any of the python code outside of the Docker container, first upgrade your version
+of Python locally. The exact way you upgrade will depend on how you originally installed Python,
+but one strongly recommended approach is to use [pyenv](https://github.com/pyenv/pyenv) which allows
+you to install and swap between different python versions locally.
+
+If you run commands with Poetry, you'll also need to [configure](https://python-poetry.org/docs/managing-environments/#switching-between-environments)
+it to use the approach python version.
+
+## Dockerfile
+The dockerfile that our API is built from specifies the Python version as the first step.
+To upgrade this, simply change the version to the version you would like to use.
+
+For example, to upgrade from 3.12 to 3.13, change the following line:
+```dockerfile
+FROM python:3.12-slim AS base
+```
+to
+```dockerfile
+FROM python:3.13-slim AS base
+```
+
+## Poetry
+Adjust the pyproject.toml file line that specifies the version of Python used
+to your new version. For example, to upgrade from 3.12 to 3.13, change it from:
+
+```toml
+[tool.poetry.dependencies]
+python = "~3.12"
+```
+
+to
+```toml
+[tool.poetry.dependencies]
+python = "~3.13"
+```
+
+You will then need to run `poetry lock --no-update` to make the lock file reflect this change.
+
+## Misc
+Some tools, include pyenv, reference the [.python-version](/app/.python-version) file in order to determine which
+version of python should be used. Update this to the approach version as well.