Migrate from runtime.txt to .python-version

[nanotaboada]

Description

The project currently uses runtime.txt to specify the Python version (python-3.13.3). This file is primarily used by cloud platforms like Heroku and some legacy deployment systems. However, the modern Python ecosystem has standardized on .python-version as the preferred method for specifying Python versions.

Current State

• File: runtime.txt contains python-3.13.3
• Usage: Not actively used in CI/CD (GitHub Actions uses hardcoded env var)
• Docker: Python version is hardcoded in Dockerfile (3.13.3)
• Status: .python-version is currently in .gitignore (line 89)

Why Migrate?

• Standardization: .python-version is supported by multiple tools (pyenv, asdf, mise, direnv)
• Developer Experience: Automatic version switching when entering the project directory
• CI/CD Integration: GitHub Actions setup-python can read from .python-version
• Consistency: Single source of truth for Python version across environments
• Modern Practice: Aligns with current Python tooling ecosystem standards

---

Proposed Solution

1. Create .python-version file

Create a new file in the project root containing only the Python version number.

2. Update .gitignore

Uncomment or remove the .python-version exclusion to track it in version control.

3. Update GitHub Actions workflow

Modify .github/workflows/python-app.yml to read version from .python-version instead of hardcoded env variable.

4. Update documentation

Update README.md to mention .python-version usage and benefits for contributors.

5. Remove runtime.txt

Delete the legacy file after confirming no deployment dependencies.

6. Consider Dockerfile updates

Optionally create a mechanism to keep Dockerfile Python version in sync.

---

Suggested Approach

Step 1: Create .python-version

Create file at project root:

3.13.3

Step 2: Update .gitignore

File: .gitignore (line ~89)

Change:

# .python-version

To:

# Track .python-version for consistent Python version across environments

Step 3: Update GitHub Actions

File: .github/workflows/python-app.yml

Before (lines 16-17):

env:
  PYTHON_VERSION: 3.13.3

After:

# PYTHON_VERSION is now read from .python-version file

Before (lines 29-31):

      - name: Set up Python ${{ env.PYTHON_VERSION }}
        uses: actions/setup-python@v6.0.0
        with:
          python-version: ${{ env.PYTHON_VERSION }}

After:

      - name: Set up Python
        uses: actions/setup-python@v6.0.0
        with:
          python-version-file: '.python-version'

Before (lines 55-57):

      - name: Set up Python ${{ env.PYTHON_VERSION }}
        uses: actions/setup-python@v6.0.0
        with:
          python-version: ${{ env.PYTHON_VERSION }}

After:

      - name: Set up Python
        uses: actions/setup-python@v6.0.0
        with:
          python-version-file: '.python-version'

Step 4: Update README.md

File: README.md

Add a new section after "About" or in "Install":

## Python Version Management

This project uses `.python-version` to specify the required Python version. If you use [pyenv](https://github.com/pyenv/pyenv), [asdf](https://asdf-vm.com/), or [mise](https://mise.jdx.dev/), the correct Python version will be automatically activated when you enter the project directory.

Alternatively, ensure you have Python 3.13.3 (or the version specified in `.python-version`) installed.

Step 5: Remove runtime.txt

Delete the file:

rm runtime.txt

Step 6 (Optional): Dockerfile Automation

Add a comment in Dockerfile at line 5 and 22:

# Python version should match .python-version file (currently 3.13.3)
FROM python:3.13.3-slim-bookworm AS builder

Or create a build script that reads .python-version and passes it as a build arg.

---

Acceptance Criteria

• .python-version file exists at project root with content 3.13.3
• .python-version is tracked in git (not ignored)
• GitHub Actions workflow successfully uses python-version-file: '.python-version'
• Both lint and test jobs in CI pass with the new configuration
• PYTHON_VERSION environment variable is removed from workflow
• runtime.txt is deleted from the repository
• README.md documents the use of .python-version
• All CI/CD checks pass (linting, testing, coverage)
• Docker builds continue to work (no regression)
• Documentation mentions benefits for developers using pyenv/asdf/mise

---

References

• GitHub Actions setup-python documentation
• pyenv documentation
• PEP 508 – Dependency specification

[edmorley]

3.13.3

I wouldn't use the full string 3.13.3, but instead the alias 3.13 (for both the .python-version file and the Dockerfile FROM image), that way it will automatically use the latest patch 3.13 without having to bump it every two months.

[nanotaboada]

Thanks for the suggestion @edmorley !

I've considered this approach, but I prefer to keep the full version 3.13.3 pinned for the following reasons:

Reproducibility & Determinism:

• Explicit patch versions ensure identical builds across all environments (local, CI, production)
• Critical for debugging - knowing the exact Python version eliminates a variable when investigating issues
• Docker builds are deterministic and cacheable with specific versions

Security & Control:

• Patch updates can introduce subtle behavioral changes or regressions
• We maintain awareness of Python releases and can test/verify before upgrading
• CVE fixes in patch releases are important, but we want to validate them first rather than auto-pulling

CI/CD Consistency:

• Our GitHub Actions cache and Docker layer cache benefit from version stability
• Unexpected patch bumps could cause cache invalidation and slower builds

Low Maintenance Burden:

• Bumping every ~2 months is manageable and keeps us engaged with Python releases
• It's an opportunity to review changelogs and test new patches deliberately
• Already have Dependabot watching for updates

While 3.13 would work fine for many projects, for this application the benefits of explicit versioning outweigh the convenience of automatic patch updates. We value predictability over convenience here.

[edmorley]

I've considered this approach, but I prefer to keep the full version 3.13.3 pinned for the following reasons:

Hi! Thank you for the reply.

I agree there are definitely trade-offs, however, I think the security component is not one to be underestimated. ie: The fact this project is still using 3.13.3 (which is ~8 months old, and 6 releases behind 3.13.9 and so missing several security updates) even after we've talked about the versions now, is a good example of how generally people forget to update :-)