Skip to content

Template 0.1.31: no silent change of a notebook's package versions, no lost work when a notebook is updated - #55

Merged
IvanHCenalmor merged 2 commits into
mainfrom
claude/template-0.1.30
Nov 16, 2026
Merged

IvanHCenalmor merged 2 commits into
mainfrom
claude/template-0.1.30

Conversation

@IvanHCenalmor

@IvanHCenalmor IvanHCenalmor commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #48, fixes #49. Design note: .tools/docs/migration_0_1_31.md.

Rebased onto template 0.1.30 (#54). #54 took the number 0.1.30, so this change is now 0.1.31: migration v0_1_30_to_v0_1_31.py, design note migration_0_1_31.md, tests test_template_sync_0_1_31.py. #54's files are kept unchanged, except two lines in its tests: tests/_v0_1_30.py also takes out the 0.1.31 change first, and test_template_sync_0_1_30.py accepts a later template version. After the merge, the whole chain was run again on the nine app copies, through 0.1.30 to 0.1.31: no SKIPPED line, the same requirements as before, and no file still names the old site address. The branch name still says 0.1.30.

Policies (approved by @IvanHCenalmor on 2026-11-16, as both issues asked)

#48: what the merge did, reproduced

Notebook A Notebook B Merged until 0.1.30 (exit 0)
numpy==1.26.4 numpy==2.0.0 numpy==2.0.0, either file order
numpy<2.0 numpy==2.0: every requirement was written as ==
numpy<2 numpy>=2.1 numpy==2.1
numpy==1.26.4 ; win32 numpy==2.0.0 ; not win32 only the second line, so no numpy on Windows

Also found:

  • scikit-image and scikit_image were treated as two packages, giving two lines that pip refuses;
  • ipywidgets==>=7.0.0 was written when no notebook gave a Python version.

Changes

  • merge_requirements.py:

    • requirements are kept as written and combined per package, with names compared as pip compares them;
    • different exact pins, a pin outside another notebook's range, or ranges no version meets stop the merge before any file is written, naming every notebook and requirement in sorted order;
    • requirements_overrides.yaml decisions (use plus a required reason) are written at the top of every generated file;
    • lines with different markers stay separate, and OS-specific lists are checked against the common ones;
    • --check only looks for conflicts;
    • build_gpu_lines / tensorflow_gpu_lines are unchanged.

    satisfiable() is our own check because a failed lock is only a warning: the installer would then install the unlocked file.

  • .tools/requirements.txt: packaging==25.0.

  • release_constructor.yml: merge_requirements.py --check after check_placeholders.py in the bump-version job. A failed merge leaves the old requirements.txt, which would otherwise be released.

  • update_on_notebook_change.yml: a push of requirements_overrides.yaml runs the workflow and the merge.

  • Welcome_template.ipynb, the Update button:

    • it asks first, says where the copy goes and to close the notebook's tab;
    • it downloads the new notebook and checks that it is one;
    • it copies the current file to <notebook>.backup-<date>.ipynb, never overwriting an earlier backup;
    • it writes the new notebook atomically, through a temporary file and a rename, and only then records the version.

    Cancel or any failure changes nothing. A private repository without a token no longer crashes the button. The app-version gate is unchanged.

  • Migration v0_1_30_to_v0_1_31.py:

    • it replaces the 0.1.30 merge script, adds packaging, and creates requirements_overrides.yaml only where notebooks already pin different versions;
    • it edits the known lines of both workflows, and adds the release check only when the app's merger knows --check;
    • it replaces the Welcome cell's handler, compared line by line with trailing spaces ignored;
    • every customised file is left alone with a SKIPPED line.
  • Docs: notebook_requirements.md (new section on conflicts), notebook_upload.md, notebook_usage.md (updating a notebook), and both troubleshooting pages.

  • Tests:

    • tests/test_template_sync_0_1_31.py (35 tests);
    • tests/_v0_1_31.py undoes the 0.1.31 changes for the older frozen-resource tests, with the 0.1.30 Welcome template frozen in tests/fixtures/template_0_1_30/.

Verified

  • With CI's versions (ruff 0.15.20, mypy 1.20.2), ruff and mypy pass.
  • The full suite on Windows has the same 58 failures as main (bash and path-separator tests) and no new ones; the 35 new tests pass.
  • Copies of NucleiSky, Playground, Guess the Condition, LabConstrictor_Demo, LabChronicle, CellTracksColab, StarDist2D, CellPatcher and VLab4Mic were synced from their own template version to 0.1.31. All migrate with no SKIPPED line.
    • On their notebooks, the new merge gives exactly the same requirements as the 0.1.30 merge.
    • NucleiSky gets 6 recorded decisions (cellpose, ipywidgets, scikit-image, tifffile, torch, zarr), and LabChronicle 1 (tqdm).
    • The release check passes.
    • The Welcome notebook is built from the new template and passes check_placeholders.py.
  • uv itself rejects numpy<2,>=2.1 ("you require numpy<2 and numpy>=2.1, which are incompatible").

Not verified

  • Nobody has clicked the confirmation dialog in an installed app; it needs a person. The backup function itself is tested: first install, backup, two updates in the same second, a non-notebook download, and a failed write.
  • No real run of Updates on notebook change or of a release has used the new scripts.

🤖 Generated with Claude Code

IvanHCenalmor and others added 2 commits November 16, 2026 09:34
…o lost work when a notebook is updated

- #48: merge_requirements.py keeps requirements as written and combines them per package (names compared as
  pip compares them). Different exact pins, a pin outside another notebook's range, or ranges no version meets
  stop the merge before any file is written, naming every notebook and requirement. requirements_overrides.yaml
  decides explicitly, with a required reason, written at the top of the generated files. Different markers stay
  separate lines; OS-specific lists are checked against the common ones. --check only looks for conflicts.
  packaging==25.0 in .tools/requirements.txt.
- The release runs merge_requirements.py --check after check_placeholders.py; a push of
  requirements_overrides.yaml runs the notebook workflow's merge again.
- #49: the Welcome notebook's Update asks first, keeps the current notebook as <notebook>.backup-<date>.ipynb,
  writes the new one atomically and records the new version only after that. Cancel or any failure changes
  nothing; a private repository without a token no longer crashes the button.
- Migration v0_1_29_to_v0_1_30.py: replaces the 0.1.29 merge script, adds packaging, creates
  requirements_overrides.yaml where notebooks already pin different versions (keeping the version used until now),
  updates the two workflows and the Welcome template's update handler; SKIPPED for customised files.
- Design note migration_0_1_30.md, docs, tests (tests/test_template_sync_0_1_30.py; tests/_v0_1_30.py keeps the
  older frozen-resource tests comparable).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
main's 0.1.30 (the site's GitHub Pages address) is kept as it is. The requirements and notebook-update change
moves to 0.1.31: migration v0_1_30_to_v0_1_31.py, resources v0_1_30_to_v0_1_31, design note migration_0_1_31.md,
tests/_v0_1_31.py and tests/test_template_sync_0_1_31.py, the frozen Welcome template in tests/fixtures/template_0_1_30.
before_0_1_30 of main takes out the 0.1.31 change first, so the older frozen-resource tests keep comparing as before;
test_template_sync_0_1_30 accepts a later template version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@IvanHCenalmor IvanHCenalmor changed the title Template 0.1.30: no silent change of a notebook's package versions, no lost work when a notebook is updated Template 0.1.31: no silent change of a notebook's package versions, no lost work when a notebook is updated Nov 16, 2026
@IvanHCenalmor
IvanHCenalmor merged commit 87b4b97 into main Nov 16, 2026
4 checks passed
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.

BLOCKER: protect locally modified notebooks from overwrite during update BLOCKER: reject or explicitly resolve conflicting notebook dependency pins

1 participant