Skip to content

fix(setup-environment): bumping cache-version builds a fresh Conda environment (#205) - #206

Merged
mmcky merged 2 commits into
mainfrom
claude/stoic-newton-u867m9-cache-version
Sep 28, 2026
Merged

mmcky merged 2 commits into
mainfrom
claude/stoic-newton-u867m9-cache-version

Conversation

@quantecon-services

@quantecon-services quantecon-services commented Sep 28, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #205. It was stacked on #204, whose chapter and descriptions it changes. Since #204's squash merge it is rebased onto main, with both commits unchanged in content.

The bug

cache-version was in the exact Conda cache key but in neither restore-keys fallback. The first fallback, conda-<os>-<name>-py<python>-<hash>-, matches the same environment file under any version. So a bump restored the previous version's environment and ran conda env update on it, and never built a fresh one.

The fix

cache-version moves ahead of the Python version and the hash, and the key has one fallback, which includes it:

key:       conda-<os>-<environment-name>-<cache-version>-py<python-version>-<hash of environment>
fallback:  conda-<os>-<environment-name>-<cache-version>-py<python-version>-
Change Before After
Bump cache-version Restores the old environment and updates it Nothing matches, so a fresh build
Edit environment.yml Restores the latest environment and updates it Same, within the version
Change python-version or environment-name Fresh build Same

Evidence: red, then green

The two runs linked below ran on the same commits before the rebase, ac7d10d and 4e99c16, whose trees are identical to these.

  • 390f7c0 adds only the new harness job, env-version-bump, against the old key layout. It runs after env-seed on the same salted fixture, with a salted cache-version, and asserts that conda-cache-hit is empty. It failed exactly as setup-environment: bumping cache-version does not give a fresh Conda environment #205 describes:

    key: conda-Linux-quantecon-py3.13-f85ac09d…-bump-36380016909-1
    Cache hit for restore-key: conda-Linux-quantecon-py3.13-f85ac09d…-v1
    ##[error]conda-cache-hit: expected empty (nothing restored) after a cache-version bump, got [false]. …
    
  • f644af9 is the fix. The same job passes, and the whole harness is green. env-hit-build still gets its exact hit under the new format.

    key: conda-Linux-quantecon-bump-36380285696-1-py3.13-0e0c895d…
    restore-keys: conda-Linux-quantecon-bump-36380285696-1-py3.13-
    Cache not found for input keys: …
    Conda: Installed fresh
    

Also in this PR

Rollout

  • One cold build per repository. The key format changes, so each repository's first standard-mode run after the release builds the environment from scratch once, as after the testing: publish/preview/cache action logic has no automated tests #100 cache-path fix. No current consumer pays this: the ones that use setup-environment run it in the quantecon-build container, where there is no Conda cache.
  • The bjc-* harness jobs until v0 moves. Their inner setup-environment@v0 keeps the old layout, so it misses env-seed's cache and solves fresh or from an older run's cache. That's slower but correct, and it resolves itself once v0 moves. There is no workaround to remove at release.
  • Staging. It changes behaviour, so it ships in the next release. The canary never runs setup-environment in standard mode, so env-seed, env-hit-build and env-version-bump are its coverage.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

By design this WIP commit adds only the failing test and omits the setup-environment key-layout fix, so the required harness check stays red and it is not mergeable until the follow-up fix lands.

Review effort: Balanced
Findings: None

What changed in this PR

This is a work-in-progress, test-first (TDD) PR that adds a single new harness job, env-version-bump, to the action-level PR harness (.github/workflows/test-actions.yml). It targets issue #205: bumping setup-environment's cache-version currently restores the previous Conda environment via a restore-keys fallback (because cache-version sits only in the exact key), so a bump never yields a fresh environment. The new job reproduces that bug by running setup-environment with a salted cache-version on env-seed's salted fixture and asserting that conda-cache-hit is empty (a true miss). On the current key layout the fallback restores env-seed's cache and reports 'false', so the job is expected to fail until the behavioural fix (moving cache-version ahead of the hash in setup-environment/action.yml) lands in a follow-up commit.

Changes:

  • Add the env-version-bump job that recreates env-seed's salted fixture, runs setup-environment with cache-version: bump-${{ env.SALT }}, and asserts conda-cache-hit is empty plus a fresh-env smoke check (import myst_nb).
  • Register env-version-bump in the harness-summary (Action harness: all checks) needs list so it is covered by the single required status check.
File Description
.github/​workflows/​test-actions.yml Adds the env-version-bump harness job (reuses the env-seed salt/fixture and asserts an empty conda-cache-hit after a cache-version bump) and wires it into the harness-summary aggregation gate.

The test logic itself is sound: the salt (run_id-run_attempt) keeps keys unique per run, env-seed is a needs: dependency so its cache is saved before this job runs, the hardcoded quantecon env name matches environment-name's default, $CONDA is a runner-default variable, and the fixture's jupyter-book dependency provides myst_nb. The harness-summary wiring is consistent with both the relevant (all-success) and not-relevant (all-skipped) branches. I found no concrete code defects to flag, so I have not stored any comments.

The one substantive point is inherent to the PR's own design rather than a code error: as it stands, this commit intentionally leaves the required Action harness: all checks job red because the corresponding setup-environment/action.yml key-layout fix is deferred to a later commit, and the branch is stacked on the unmerged #204.


💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@quantecon-services
quantecon-services marked this pull request as ready for review September 28, 2026 05:09
Base automatically changed from claude/stoic-newton-u867m9 to main September 28, 2026 05:12
…ronment (#205)

A new harness job, env-version-bump, runs after env-seed on the same
salted fixture with a salted cache-version, and asserts that
conda-cache-hit is empty: nothing restored. On the current key layout
it fails by design. Fallback 1, conda-<os>-<name>-py<ver>-<hash>-,
omits cache-version, so it restores env-seed's cache and the output is
'false'. The fix follows in the next commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb
…vironment (#205)

cache-version was in the exact cache key but in neither restore-keys
fallback, and the first fallback matched the same environment file
under any version. So a bump restored the previous version's
environment and ran `conda env update` on it, never a fresh build. The
previous commit's harness job shows it: the bumped key missed, fallback
1 restored env-seed's ...-v1 cache, and conda-cache-hit was 'false'.

cache-version now comes before the Python version and the file hash,
and the key has one fallback, which includes it:

  key:      conda-<os>-<name>-<cache-version>-py<python>-<hash>
  fallback: conda-<os>-<name>-<cache-version>-py<python>-

An edit to the environment file still restores the latest environment
of the same version and updates it; a bump, a Python change or a name
change restores nothing. The key format changes, so the first
standard-mode run after the release builds from scratch once. No
current consumer runs setup-environment in standard mode.

- cache-version and conda-cache-hit descriptions, and the chapter's
  generated table, cache-key table and troubleshooting, follow.
- QUICK-REFERENCE's advice to bump cache-version is right again, so
  #204's notes against it are reverted; only its key format changes.
- CHANGELOG: a Fixed entry, and #204's Documentation entry no longer
  describes the old behaviour. TESTING's coverage row and PLAN follow.
- The bjc-smoke comment no longer assumes @v0 shares the key format.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb
@quantecon-services
quantecon-services force-pushed the claude/stoic-newton-u867m9-cache-version branch from 4e99c16 to f644af9 Compare September 28, 2026 05:13
@mmcky
mmcky merged commit 560053c into main Sep 28, 2026
25 checks passed
@mmcky
mmcky deleted the claude/stoic-newton-u867m9-cache-version branch September 28, 2026 05:17
mmcky pushed a commit that referenced this pull request Sep 28, 2026
…idy up after #206 (#208)

#206 tested one half of #205: a cache-version bump restores nothing.
Nothing checked the other half, that an edited environment file under
the same version still restores through the fallback. A change that
dropped the fallback would have left the harness green while every
edit cost a full build.

- New harness job, env-file-edit: env-seed's salted fixture plus one
  line, so only the fallback can match, and conda-cache-hit must be
  'false'. env-seed has saved a cache under the same version, so the
  result is deterministic.
- setup-environment's closing summary tells the fallback case apart
  ("Restored from an earlier cache, then updated from the environment
  file") instead of reporting it as "Installed fresh".
- env-seed's success line no longer claims the environment was created
  fresh: it usually comes from another run's cache through the
  fallback.
- TESTING.md: the stale cache-key debug snippet becomes a pointer to
  the cache step's log and the chapter's key table; the coverage row
  gains the new job. CHANGELOG's #205 entry covers both.


Claude-Session: https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb

Co-authored-by: Claude <noreply@anthropic.com>
mmcky added a commit that referenced this pull request Nov 5, 2026
Move [Unreleased] into a dated 0.13.0 section (decision 11, 2026-11-04), and record the deploy-CLI moves since v0.12.0 (#207, #219), which Dependabot made without a CHANGELOG entry. The release carries #198, #206 and #210 to @v0 consumers, so it is staged on the canary before v0 moves. This commit changes only CHANGELOG.md, and the harness has no @v0 workaround for this release to drop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMbMmeUUEj8EjiweB6S
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

setup-environment: bumping cache-version does not give a fresh Conda environment

4 participants