Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Pin Python minor version and document upgrade details #235

Merged
merged 2 commits into from
Aug 28, 2024
Merged

Pin Python minor version and document upgrade details #235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e1bf104
Pin Python minor version and document upgrade details
chouinar Aug 26, 2024
c4670ee
Restructuring upgrade guide
chouinar Aug 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion app/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions app/poetry.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 3 additions & 1 deletion app/pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
27 changes: 27 additions & 0 deletions docs/app/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading