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

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

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.

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.