feat: switch workspace default branches from release to main with version-paired tags #71

Affected Repositories

• autolens_workspace (primary — most affected by the bug)
• autogalaxy_workspace
• autofit_workspace
• PyAutoFit (docs)
• PyAutoGalaxy (docs)
• PyAutoLens (docs)
• PyAutoConf (new workspace.check_version helper)
• PyAutoBuild (release.yml, tag_and_merge.py, CLAUDE.md)
• admin_jammy (skills + claude.md sweep)

Work Classification

Both — library-side changes (PyAutoBuild, PyAutoConf, library docs) come first via /start_library; workspace version.txt commits and welcome.py wiring follow.

Branch Survey

Suggested branch: feature/default-branch-release-to-main
Worktree root: ~/Code/PyAutoLabs-wt/default-branch-release-to-main/ (created later by /start_library)

Implementation Steps

Phase 1 — GitHub admin (no code)

1. gh repo edit PyAutoLabs/{autofit,autogalaxy,autolens}_workspace --default-branch main — flip defaults.
2. Verify each with gh repo view PyAutoLabs/<repo> --json defaultBranchRef --jq '.defaultBranchRef.name'. Expect main.

Phase 2 — PyAutoBuild release-branch removal
3. PyAutoBuild/.github/workflows/release.yml — rewrite the release_workspaces job (lines 683-692) to skip the release checkout. Commit notebooks to main, write version.txt, tag the workspace at vYYYY.M.D.N matching the library tag, push tags. Same fix for run_notebooks_and_release_workspaces (lines 797-817).
4. PyAutoBuild/autobuild/tag_and_merge.py — delete the dead release checkout block (line 38); activate the workspace-tagging path so workspaces get a tag matching the library version.
5. PyAutoBuild/CLAUDE.md — drop the "Updating workspace release branches" bullet (line 11) and the update_notebook_visualisations description (line 124).

Phase 3 — Workspace versioning bootstrap
6. Add version.txt (placeholder = current latest tag 2026.4.13.6) to each workspace; release pipeline overwrites on every release.
7. PyAutoConf — add autoconf.workspace.check_version(library_version) that reads <cwd>/version.txt, raises WorkspaceVersionMismatchError. Env override: PYAUTO_SKIP_WORKSPACE_VERSION_CHECK=1.
8. Wire the check into each workspace's welcome.py (single bootstrap location, runs once when user first verifies install).

Phase 4 — Library docs
9. Update docs/installation/{pip,conda}.rst in PyAutoFit, PyAutoGalaxy, PyAutoLens — change bare workspace git clone … --depth 1 to a versioned git clone --branch v<library_version> … snippet.

Phase 5 — admin_jammy skills + CLAUDE.md sweep
10. Scan and update all 8 admin_jammy files with release references:
- admin_jammy/skills/ship_workspace/ship_workspace.md — remove --base main IMPORTANT block (lines ~68-71).
- admin_jammy/skills/ship_library/ship_library.md
- admin_jammy/skills/start_workspace/start_workspace.md
- admin_jammy/skills/review_release/review_release.md
- admin_jammy/skills/pre_build/pre_build.md
- admin_jammy/skills/dep_audit/SKILL.md
- admin_jammy/skills/verify_install/verify_install.md
- admin_jammy/claude.md, admin_jammy/software/build.md

Phase 6 — Verification
11. gh repo view PyAutoLabs/<repo> --json defaultBranchRef × 3 — confirm defaults stuck.
12. grep -rn '\brelease\b' PyAutoBuild/ admin_jammy/ — only legitimate hits should remain (release-notes, pypi release, GitHub Releases).
13. (Future, not in this PR) Decide whether to delete the release branches from origin entirely — destructive; keep as separate confirmation step.

Key Files

• PyAutoBuild/.github/workflows/release.yml — remove release checkout in workspace-release jobs
• PyAutoBuild/autobuild/tag_and_merge.py — activate workspace tagging
• PyAutoBuild/CLAUDE.md — drop release-branch documentation
• PyAutoConf/autoconf/workspace.py (new) — version-mismatch helper
• autofit_workspace/version.txt, autogalaxy_workspace/version.txt, autolens_workspace/version.txt — new
• autofit_workspace/welcome.py, autogalaxy_workspace/welcome.py, autolens_workspace/welcome.py — wire version check
• PyAutoFit/docs/installation/{pip,conda}.rst, PyAutoGalaxy/docs/installation/{pip,conda}.rst, PyAutoLens/docs/installation/{pip,conda}.rst
• admin_jammy/skills/**/*.md — sweep release refs

Three workspace repos currently have release set as their GitHub default branch. release is supposed to be a downstream branch updated only by PyAutoBuild when it merges main → release during a release cut. Having release as the default means gh pr create without --base main, and the GitHub UI "Compare & pull request" button, both silently target release. PRs that land on release are orphaned from main's history and get overwritten by the next main → release sync.

This already happened: autolens_workspace PRs #54, #55, #58, #59, #61 and autogalaxy_workspace PR #28 were merged to release over 2026-04-13 → 2026-04-14 without anyone noticing. All have since been replayed onto main via cherry-pick PRs (autolens_workspace #62, #63 and autogalaxy_workspace #29), but the underlying misconfiguration is still there and will keep causing drift until fixed.

Reason

Currnetly, release is what links to the pypi release, such that if a user runs pip install autolens, the
release branch should be in sync.

What we should do instead is have workspaces use main, but have it so the two following things happen:

1. Workspaces have tagged or version github branches, so that when a PyAuto version is released users can pair it to a specific workspace.
2. All PyAutoFit / PyAutoGalaxy / PyAutoLens docs tell the user (e.g. during installation) to use a version number for the workspace clone or download, paired to their version.
3. If a user has an out of sync workspace and source code, they get an error they have to manually disable.

This will mean a user can run the main branches of the source repos and workspace repos without issue.

Action

On each of the three repos, change the default branch from release back to main:

• https://github.com/PyAutoLabs/autolens_workspace/settings/branches — set default to main
• https://github.com/PyAutoLabs/autogalaxy_workspace/settings/branches — set default to main
• https://github.com/PyAutoLabs/autofit_workspace/settings/branches — set default to main

(autolens_workspace_test is already correct — default is main.)

Then add solution to points 1), 2) and 3) above.

Verification

After each change, confirm with:

gh repo view PyAutoLabs/<repo> --json defaultBranchRef --jq '.defaultBranchRef.name'

Expect main for all four workspace repos.

Why not purely rely on the /ship_workspace skill fix?

The skill has already been patched to pass --base main explicitly on every gh pr create call (admin_jammy commit 8152d05). That covers Claude-driven shipping. It does NOT cover:

• PRs opened manually in the GitHub UI (the "Compare & pull request" banner defaults to the repo's default branch).
• PRs from contributors who don't use the shipping skill.
• git push -u origin <branch>'s suggested PR URL (pre-fills the default base).

So changing the repo default is the root-cause fix; the skill patch is defence-in-depth.

So, also remove this fix once we are on main everywhere.