Dependencies Management

Dependencies Management

Update Dependencies

Instructions to update project dependencies (including Github actions used by CI workflows).

1. Prepare the branch

Create a new branch (following the naming convention in @AGENTS.md).

2. Update the lock file and environment

Update uv:

uv self update --token $GITHUB_TOKEN

IMPORTANT: updating uv MUST NOT be skipped. If the above command fails (e.g. due to a GitHub API rate limit), try the following fallbacks in order until uv --version confirms the latest version is active on PATH:

Fallback 1 — official install script (preferred; replaces PATH binary directly):

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env  # refresh current shell session
uv --version                 # verify PATH binary is now updated

Fallback 2 — pip (use only if curl is unavailable):

pip install --user --upgrade uv
uv --version   # check if PATH binary was updated

Once uv is up to date, run:

uv lock --upgrade  # update the lock file
uv export --format requirements-txt --no-emit-project --no-hashes --no-dev -o requirements.txt  # sync @requirements.txt with @uv.lock
uv sync --inexact  # update environment to match @uv.lock

3. Update GitHub Actions versions

For each uses: <owner>/<repo>@<version> entry across all files in .github/workflows/, retrieve the latest release tag by fetching the releases page with WebFetch:

url:    https://github.com/<owner>/<repo>/releases/latest
prompt: What is the latest release tag for this GitHub action?

In each case update the version pin to any more recent release. Preserve the existing pinning style, so if the current pin is a specific version such as @v3.0.1, update to the full latest version string, whilst if it's a major-version tag such as @v4, update to any new major-version tag (if the project no longer publishes a major-version tag then switch to the full semver).

4. Update pre-commit hook versions

For each repo: entry in .pre-commit-config.yaml, retrieve the latest release tag by fetching the releases page with WebFetch:

url:    https://github.com/<owner>/<repo>/releases/latest
prompt: What is the latest release tag for this pre-commit hook?

In each case update the rev: pin to any more recent release. Preserve the existing pinning style, so if the current pin is a specific version such as v6.0.0, update to the full latest version string, whilst if it's a major-version tag such as @v4, update to any new major-version tag (if the project no longer publishes a major-version tag then switch to the full semver).

5. Test

Before running the tests check whether the test environment has live access to the required network endpoints by running:

python -c "
import urllib.request, sys

for label, url in [
    ('yahoo', 'https://query1.finance.yahoo.com/v8/finance/chart/MSFT?interval=1d&range=1d'),
    ('raw.github.com', 'https://raw.githubusercontent.com/'),
]:
    try:
        urllib.request.urlopen(url, timeout=10)
        print(f'{label}: reachable')
    except Exception as e:
        print(f'{label}: unreachable ({e})')
"

Then, run the test suite with options as determined by the reachability results:

• If both reachable: run the full test suite:

  uv run pytest -v

• otherwise use the pytest --ignore option to exclude the test module(s) correponding with the unreachable service(s):
  • if yahoo unreachable then '--ignore=tests/test_yahoo.py'
  • if raw.github.com unreachable then '--ignore=tests/test_calendar_utils.py' For example, if both yahoo and raw.github.com are unreachable then the command will be:

  uv run pytest --ignore=tests/test_yahoo.py --ignore=tests/test_calendar_utils.py -v

Interpreting the local test results:

• All tests pass and no raised warning is fixable (see Fixable warnings section below) → go to step 7 to raise PR.
• All failing tests are in tests/test_yahoo.py and/or tests/test_calendar_utils.py and no raised warning is fixable → test failures probably due to a transient network issue (see Network tests section below), go to step 7 to raise PR.
• Failure of any other test or a fixable warning raised → proceed to step 6 to fix.

6. Fix

Any failing tests and fixable warnings will likely have their origin in changes to the dependencies. To provide support for the latest dependencies MAKE REVISIONS to the code base to fix:

• code causing tests to fail.
• all fixable warnings (see Fixable warnings section below).

As a general RULE, change the package code to get the tests passing, not the test code! You may make changes to the test code only with good reason and only when this does not impair the test's efficacy.

To facilitate identifying the cause of test failures consider researching the changelogs of updated dependencies for versions released since the previously locked version.

Iterate on this process until:

• all tests are passing with the exception of any requiring unreachable services.
• all fixable warnings have been fixed.

IMPORTANT: in this step you should not run the full test suite, rather validate fixes by re-running only the previously failing tests. Example to run a specific test:

pytest tests/test_module.py::test_name

7. Raise PR

Once local tests pass, commit all changes to the branch and raise a PR.

• PR title: Title the PR as Update Dependencies <MM> <DD> (auto) where:
  • <MM> should be replaced with the first three letters of the current month, the first of which should be capitalized.
  • <DD> should be replaced with the current day of the month as represented by two digits. Example title: Update Dependencies Apr 07 (auto)
• label: Add the 'dependencies' label to the PR.
• otherwise comply with the package's 'create-pr' skill.

8. Subscribe to PR activity

By raising the PR a GitHub CI workflow will be triggered. Subscribe to the raised PR's activity.

Proceed to step 9 when you receive an event indicating that the triggered workflow has completed.