feat: workspace version check via config/general.yaml on every library import

[Jammy2211]

Overview

Workspace/library version mismatches today only surface when users run welcome.py — which most users execute once and then never again. Every other script imports the library and loads config, but never calls check_version, so a stale-workspace-vs-fresh-library mismatch goes undetected and produces confusing API errors. This task moves the check into every library's __init__.py, embeds the canonical version inside config/general.yaml so it travels with the user's config directory (even when scripts are copy-pasted into their own drive), and adds a YAML override flag so users on main-branch clones — where mismatches are expected — can opt out without an env var.

Plan

• Move the workspace-version check from welcome.py into every library's __init__.py so every script run from a workspace triggers it on import.
• Embed the workspace version inside config/general.yaml under the existing version: key, so the version travels with the user's config directory. version.txt stays as the build-time canonical source.
• Add a workspace_version_check: True/False flag to version: in general.yaml, mirroring the existing python_version_check pattern, so users can disable the check without setting an env var.
• Rewrite the mismatch error to explicitly mention: (a) the YAML override, (b) that users on main branch clones should disable it since main updates faster than releases, and (c) the existing PYAUTO_SKIP_WORKSPACE_VERSION_CHECK env-var escape hatch.
• Update the release pipeline to write the version into config/general.yaml on every release (in addition to version.txt), and update verify_workspace_versions.sh to check both sources.
• Backfill workspace_version: 2026.4.13.6 and workspace_version_check: True into all 7 workspaces' general.yaml.

Detailed implementation plan

Affected Repositories

• PyAutoConf (primary — core check logic + tests)
• PyAutoFit (call check from __init__.py)
• PyAutoGalaxy (call check from __init__.py)
• PyAutoLens (call check from __init__.py)
• PyAutoBuild (release pipeline + verify script)
• autofit_workspace, autogalaxy_workspace, autolens_workspace (config + welcome.py)
• HowToFit, HowToGalaxy, HowToLens (config + welcome.py for HowToLens)
• euclid_strong_lens_modeling_pipeline (config)

Work Classification

Both — library work first, workspace follows after the library PRs are merged so the libraries can be re-installed and the new YAML keys exercised.

Branch Survey

Repository	Current Branch	Dirty?
PyAutoConf	main	clean
PyAutoFit	main	1 file (unrelated)
PyAutoGalaxy	main	1 file (unrelated)
PyAutoLens	main	1 file (unrelated)
PyAutoBuild	main	clean
autofit_workspace	main	clean
autogalaxy_workspace	main	2 files (unrelated)
autolens_workspace	main	13 files (unrelated)
HowToFit	main	2 files (unrelated)
HowToGalaxy	main	clean
HowToLens	main	2 files (unrelated)
euclid_strong_lens_modeling_pipeline	main	clean

Suggested branch: feature/workspace-version-config-check
Worktree root: ~/Code/PyAutoLabs-wt/workspace-version-config-check/ (created by /start_library)

Implementation Steps

1. PyAutoConf — extend autoconf/workspace.py::check_version()

• Source-of-truth precedence: read <workspace_root>/config/general.yaml first; if version.workspace_version is set, use it. Fall back to <workspace_root>/version.txt. Skip with warning if neither is found.

• Bypass precedence: PYAUTO_SKIP_WORKSPACE_VERSION_CHECK=1 env var (existing) or version.workspace_version_check: False in general.yaml (new) → return early.

• New mismatch error message:

  Workspace version (X.Y.Z) at /path does not match the installed library
  version (A.B.C).
  
  This usually means your installed library was upgraded but your workspace
  clone is from an older release tag. Re-clone the workspace at the matching
  tag:
  
      git clone --branch A.B.C <workspace-repo-url>
  
  To bypass this check, edit `config/general.yaml`:
  
      version:
        workspace_version_check: False
  
  IMPORTANT: If you cloned the workspace from `main` rather than a release
  tag, you should set `workspace_version_check: False`. The `main` branch
  updates much more frequently than library releases, so version mismatches
  are expected and not actionable for `main`-branch users.
  
  You can also set the environment variable
  PYAUTO_SKIP_WORKSPACE_VERSION_CHECK=1 to disable temporarily.
  

• Same friendly text for the missing-config / missing-version-file warning — point at the YAML override and explain the main branch case.

2. PyAutoConf — extend test_autoconf/test_workspace.py

New tests for: YAML version source, YAML bypass flag, YAML override beats env, both sources missing → warning, only version.txt present (legacy fallback), YAML and version.txt disagree (YAML wins).

3. PyAutoFit, PyAutoGalaxy, PyAutoLens — call check on import

In each library's __init__.py, after __version__ is defined:

from autoconf import check_version
check_version(__version__)

PyAutoArray is NOT modified — no autoarray-only workspace exists; the check fires through autofit/autogalaxy/autolens.

4. Workspace config/general.yaml updates (7 repos)

Add to existing version: block in each of:

• autofit_workspace, autogalaxy_workspace, autolens_workspace
• HowToFit, HowToGalaxy, HowToLens
• euclid_strong_lens_modeling_pipeline

version:
  python_version_check: True
  workspace_version: 2026.4.13.6   # NEW — must match the installed library version
  workspace_version_check: True    # NEW — set to False on main-branch clones

5. welcome.py cleanup

Remove the now-redundant check_version(...) call from each welcome.py (autofit/autogalaxy/autolens workspaces + HowToLens).

6. PyAutoBuild release pipeline updates

• release.yml: extend the Write workspace version.txt step to also patch config/general.yaml's version.workspace_version (Python shim — sed-based YAML edits are too fragile).
• verify_workspace_versions.sh: prefer config/general.yaml's workspace_version when present, fall back to version.txt. If both exist and disagree, fail.
• Update PyAutoBuild/CLAUDE.md to describe the new precedence.

Key Files

• PyAutoConf/autoconf/workspace.py — core check logic
• PyAutoConf/test_autoconf/test_workspace.py — new tests
• PyAutoFit/autofit/__init__.py — add 2 lines at end
• PyAutoGalaxy/autogalaxy/__init__.py — add 2 lines at end
• PyAutoLens/autolens/__init__.py — add 2 lines at end
• <7 workspaces>/config/general.yaml — add two version: keys
• <4 workspaces>/welcome.py — remove duplicate check
• PyAutoBuild/.github/workflows/release.yml — pipeline patch general.yaml
• PyAutoBuild/verify_workspace_versions.sh — read from config first
• PyAutoBuild/CLAUDE.md — document precedence

Testing approach

• PyAutoConf: pytest covers all branches of check_version.
• Libraries: import each in a workspace dir → no error; cd /tmp && python -c "import autolens" → warning (no config). Set workspace_version_check: False → silenced. Mutate general.yaml to a bogus version → raises with friendly message.
• Workspaces: python welcome.py and a representative script (scripts/imaging/modeling/start_here.py) both work with PYAUTO_TEST_MODE=1.
• PyAutoBuild: dry-run verify_workspace_versions.sh against current state — must still pass.

Original Prompt

Click to expand starting prompt

A common problem is users pair a workspace with a different version to their installed software, leaidng to API
inconsistencies and config mismatches.

What do you think we can do about this? One option would be if they are running inside a workspace, it has its
version stored somewhere which is compared to their source code on import. However, you could still end up
with users doing work outside their workspace and copy and pasting old code and API and whatnot. This version number
could be put in configs to be a bit more secure (e.g. even in their own drive they probably need a config)
but not clear cut.

[Jammy2211]

Library PRs Created — 2026-04-30

PRs

• feat(workspace): config-aware version check with YAML bypass #101 (autoconf — config-aware check_version + YAML bypass)
• feat: check workspace version on import PyAutoFit#1241 (autofit — check_version on import)
• feat: check workspace version on import PyAutoGalaxy#380 (autogalaxy — check_version on import)
• feat: check workspace version on import PyAutoLens#484 (autolens — check_version on import)
• feat(release): embed workspace_version in config/general.yaml PyAutoBuild#70 (release pipeline writes general.yaml + verify script reads it)

Status

Workspace changes needed. Next: /start_workspace.

API Changes

autoconf.workspace.check_version is unchanged in signature but its resolution and bypass behaviour are extended:

• New source-of-truth precedence: config/general.yaml → version.txt → warn.
• New YAML bypass: version.workspace_version_check: False in general.yaml (intended for main-branch clones where mismatches are expected).
• New error/warning text explicitly points users at the YAML override and calls out the main-branch case.

import autofit / autogalaxy / autolens now triggers the check on import, not just from welcome.py.

Workspace Impact

• 0 workspace scripts touched.
• 6 welcome.py files contain a now-redundant check_version(...) call to remove.
• 7 workspaces need version.workspace_version + version.workspace_version_check: True added to config/general.yaml so the config-aware path becomes the active source of truth (legacy version.txt fallback continues to work in the meantime).

[Jammy2211]

Smoke Test Results — 2026-04-30

All 7 smoke tests passed across autolens_workspace.

Workspace	Passed	Failed	Total
autolens_workspace	7	0	7

This run served as the canonical gate for the config-only change across all 7 workspaces (workspace_version embed + welcome.py duplicate check removal). No script logic was touched.

[Jammy2211]

Shipped — 2026-04-30

PRs

Workspace (7):

• feat: embed workspace_version in config + drop welcome.py duplicate check autolens_workspace#112
• feat: embed workspace_version in config + drop welcome.py duplicate check autofit_workspace#48
• feat: embed workspace_version in config + drop welcome.py duplicate check autogalaxy_workspace#51
• feat: embed workspace_version in config + drop welcome.py duplicate check HowToFit#4
• feat: embed workspace_version in config + drop welcome.py duplicate check HowToGalaxy#4
• feat: embed workspace_version in config + drop welcome.py duplicate check HowToLens#5
• feat: embed workspace_version in config/general.yaml euclid_strong_lens_modeling_pipeline#10

Upstream PRs (library, 5)

• feat(workspace): config-aware version check with YAML bypass #101
• feat: check workspace version on import PyAutoFit#1241
• feat: check workspace version on import PyAutoGalaxy#380
• feat: check workspace version on import PyAutoLens#484
• feat(release): embed workspace_version in config/general.yaml PyAutoBuild#70

Summary

Workspace/library version mismatches now surface on every script run, not just welcome.py. autoconf.workspace.check_version was extended to read config/general.yaml's version.workspace_version (with version.txt as legacy fallback) and a new version.workspace_version_check: False YAML override mirrors the existing python_version_check pattern. PyAutoFit, PyAutoGalaxy, and PyAutoLens now call the check on import. The release pipeline writes the new YAML key alongside version.txt, and verify_workspace_versions.sh reports ok for all 7 workspaces (euclid_pipeline went from SKIP to ok).

Session Notes

• Picked option B (config-embedded version) over A (library __init__ reads version.txt) because the user explicitly wanted the version to survive users copy-pasting scripts out of the workspace into their own drive — they still need a config dir to run anything, so the config travels.
• Dual bypass by request: existing PYAUTO_SKIP_WORKSPACE_VERSION_CHECK=1 env var plus the new YAML flag. The new error/warning text explicitly recommends the YAML route and calls out the main-branch case ("main updates faster than releases, so mismatches are expected and not actionable for main-branch users").
• YAML edits in release.yml use a regex-based Python shim instead of PyYAML round-trip — PyYAML strips comments, and the workspace general.yaml files are heavily commented. The shim handles both "key present (in-place replace)" and "key missing (insert under existing version: block, or append new block at end)".
• No smoke test was run at ship time because the workspace changes are purely additive YAML keys + welcome.py line removals (no script logic touched). Pre-flight covered library-import silence from each workspace + verify_workspace_versions.sh = ok. CI smoke tests on the PRs were the final gate.
• euclid_strong_lens_modeling_pipeline previously had no version.txt so was always SKIPped by verify_workspace_versions.sh — now joins the standard flow.