Checklists for upgrading packages and upgrading Python - Public Notes

In the spirit of creating public notes (which I heard about from Ryan Cheley during his talk at DjangoCon US 2023), I’m posting on the chance it could be helpful for anyone else who is also learning.

Feedback welcome - as with everything, I’m sure there are iterations to be made as I learn more (just please keep in mind that I’m a beginner if responding).

Upgrading packages checklist [check ~monthly]

  • Check for deprecation warnings by running the project’s tests
    python -Wa test >>> use if using Django Test module
    PYTHONWARNINGS=always pytest --capture=no >>> use if using pytest

    • For each deprecation warning, address what it’s warning about & then rerun the tests
  • Check if there are any outdated dependencies / package versions in the project:
    pip list --outdated

  • For each outdated package,

    • In (or file, update the version number of OutdatedPackageName to upgrade to the next incremental (e.g. from X.Y.Z to X.Y+1.Z to X.Y+2.X) release
      Note: OutdatedPackageName~=2.1.0 will install the latest version of OutdatedPackageName 2.1.X where X will update automatically when syncing your venv if a newer version is available (aka you won’t manually need to type the 2.1.1 to 2.1.2 to 2.1.3 updates in the file each time)
      Note: Search for “OutdatedPackageName X.X.X Release Notes” to find info about changes in that version. Likely will also be in OutdatedPackageName GitHub Repo
  • Save file

  • Compile updated requirements.txt or (dev-requirements.txt)

  • Sync your venv to make it match your dev-requirements.txt file
    pip-sync dev-requirements.txt
    Note: you always sync the dev-requirements.txt file (even if you only updated the file) because the dev requirements inherit the requirements.txt too and you’re using the dev requirements locally (so the venv should always be updated to match any update)

  • Double-check that the venv has the correct updated version number
    pip freeze

  • Commit changes to Git
    git status
    git add -A
    git commit -m ‘upgraded OutdatedPackageName version to X.X.X; updated requirements files’

  • Double-check everythings OK by running the project’s tests again
    python -Wa test >>> use if using Django Test module
    PYTHONWARNINGS=always pytest --capture=no >>> use if using pytest

Upgrading Homebrew / Python checklist (Mac) [check every ~3 months]

  • Find the version of Python your project currently uses in venv
    python --version

  • Find the release date of the version currently used and compare it to the release date of the newer versions of Python
    Download Python |

  • Upgrade Python version (& other outdated stuff in Homebrew)

    • Ensure Homebrew is installed
      brew --version
    • Update Homebrew
      brew update
    • See outdated Homebrew packages
      brew outdated
    • Upgrade Homebrew packages
      brew upgrade
      Note: if desired, can do one at a time instead of all at once; more info

Some assumptions

  • Mac
  • pytest
  • pip-tools

Some sources