From 17bd873d9a93b444055c842d5b1586b2c21d8ea8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Hidalgo?= <47150974+IvanHCenalmor@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:07:42 +0200 Subject: [PATCH] Template 0.1.36: the plugins are no longer experimental; no page of examples The napari, Fiji and QuPath plugins are an implemented way to use an app: "experimental" is dropped from the title of tools_bridge.md, its entry in the docs README and its line in README.md. An app's own maturity (`status: Experimental` in labconstrictor-app.yaml) is unchanged. The "Examples" section of the guides goes: use_cases.md is removed (since 0.1.35 it only pointed to the App Centre, which lists the apps), with its entry in the docs README and the "See what others have built" line of README.md. Migration 0.1.35 -> 0.1.36 delivers it: use_cases.md is removed only when it is the 0.1.35 template file (an app's own page is kept, SKIPPED), the other files get exact-text edits, line endings are kept. Design note migration_0_1_36.md, tests, and tests/_v0_1_36.py: before_0_1_36 chained into the older helpers, template_bytes gives the frozen copy of the removed page to the 0.1.29, 0.1.30 and 0.1.35 tests. Co-Authored-By: Claude Opus 5.5 --- .template_sync/manifest.yaml | 5 +- .../migrations/v0_1_35_to_v0_1_36.py | 133 +++++++++++ .../previous/.tools}/docs/use_cases.md | 0 .tools/docs/README.md | 6 +- .tools/docs/migration_0_1_36.md | 35 +++ .tools/docs/tools_bridge.md | 2 +- README.md | 3 +- tests/_v0_1_30.py | 3 +- tests/_v0_1_35.py | 3 + tests/_v0_1_36.py | 50 ++++ tests/test_template_sync_0_1_29.py | 3 +- tests/test_template_sync_0_1_30.py | 5 +- tests/test_template_sync_0_1_35.py | 28 ++- tests/test_template_sync_0_1_36.py | 222 ++++++++++++++++++ 14 files changed, 474 insertions(+), 24 deletions(-) create mode 100644 .template_sync/migrations/v0_1_35_to_v0_1_36.py rename {.tools => .template_sync/resources/v0_1_35_to_v0_1_36/previous/.tools}/docs/use_cases.md (100%) create mode 100644 .tools/docs/migration_0_1_36.md create mode 100644 tests/_v0_1_36.py create mode 100644 tests/test_template_sync_0_1_36.py diff --git a/.template_sync/manifest.yaml b/.template_sync/manifest.yaml index aeb683c..8711dbd 100644 --- a/.template_sync/manifest.yaml +++ b/.template_sync/manifest.yaml @@ -1,4 +1,4 @@ -template_version: 0.1.35 +template_version: 0.1.36 migrations: - from: 0.0.0 to: 0.0.1 @@ -111,3 +111,6 @@ migrations: - from: 0.1.34 to: 0.1.35 script: migrations/v0_1_34_to_v0_1_35.py + - from: 0.1.35 + to: 0.1.36 + script: migrations/v0_1_35_to_v0_1_36.py diff --git a/.template_sync/migrations/v0_1_35_to_v0_1_36.py b/.template_sync/migrations/v0_1_35_to_v0_1_36.py new file mode 100644 index 0000000..5fda46d --- /dev/null +++ b/.template_sync/migrations/v0_1_35_to_v0_1_36.py @@ -0,0 +1,133 @@ +"""Template 0.1.35 -> 0.1.36: the napari, Fiji and QuPath plugins are no longer called experimental, and the page of examples is gone. + +Design note: https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_36.md + +The plugins that run an app's tools in napari, Fiji and QuPath are now an implemented way to use an app, not an experiment. The "Examples" +section of the guides had one page, use_cases.md, which since 0.1.35 only pointed to the App Centre; the App Centre lists the apps, so the +page and the links to it go. + +What this changes in an app repository (every step is independent and idempotent): + +1. .tools/docs/use_cases.md is removed when it is still the 0.1.35 template file. A file the app changed itself stays as it is (SKIPPED): it + is the app's own page. This is the only file the migration deletes. +2. .tools/docs/tools_bridge.md: "experimental" is dropped from the title. +3. .tools/docs/README.md: "experimental" is dropped from the entry of the tools guide, and the "Examples" section (use_cases.md) goes. +4. README.md: "experimental" is dropped from the line of the tools guide, and the "See what others have built" line (use_cases.md) goes. + +Steps 2 to 4 replace exact pieces of template text and leave a passage alone when its text is not there (SKIPPED). The line endings of each +file are kept. The changes reach users with the app's next release. +""" +from __future__ import annotations + +from pathlib import Path +from typing import Any + + +DOCS_URL = "https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_36.md" +TAG = "[migration 0.1.36]" +RESOURCE_ROOT = Path(__file__).resolve().parents[1] / "resources" / "v0_1_35_to_v0_1_36" +PREVIOUS_ROOT = RESOURCE_ROOT / "previous" + +DOCS = Path(".tools/docs") +USE_CASES_DOC = DOCS / "use_cases.md" +TOOLS_DOC = DOCS / "tools_bridge.md" +DOCS_INDEX = DOCS / "README.md" +ROOT_README = Path("README.md") + +# Files removed, only when they are the 0.1.35 template file (compared with LF line endings). +REMOVED_FILES = (USE_CASES_DOC,) + +# (old, new) pairs, written with LF line endings; a file with CRLF line endings gets them with CRLF. Each new text is distinct from the +# old one and not contained in it, so a pair that removes a line keeps its neighbours in both texts. +EDITS: dict[Path, tuple[tuple[str, str], ...]] = { + TOOLS_DOC: ( + ("# Expose your app's tools to napari, Fiji and QuPath (optional, experimental)\n", + "# Expose your app's tools to napari, Fiji and QuPath (optional)\n"), + ), + DOCS_INDEX: ( + ("- [Expose tools to napari, Fiji and QuPath (experimental)](tools_bridge.md)\n", + "- [Expose tools to napari, Fiji and QuPath](tools_bridge.md)\n"), + ("- [Hide code cells in notebooks](code_hiding.md)\n\n## Examples\n\n- [LabConstrictor use cases](use_cases.md)\n\n## GitHub management\n", + "- [Hide code cells in notebooks](code_hiding.md)\n\n## GitHub management\n"), + ), + ROOT_README: ( + ("- [Offer your app's functions in napari, Fiji and QuPath](.tools/docs/tools_bridge.md) (experimental)\n", + "- [Offer your app's functions in napari, Fiji and QuPath](.tools/docs/tools_bridge.md)\n"), + ("(.tools/docs/notebook_portability.md)\n- [See what others have built](.tools/docs/use_cases.md)\n- [All guides]", + "(.tools/docs/notebook_portability.md)\n- [All guides]"), + ), +} +FILES = (*REMOVED_FILES, *EDITS) + + +def log(message: str) -> None: + print(f"{TAG} {message}") + + +def apply_edits(text_lf: str, edits: tuple[tuple[str, str], ...]) -> tuple[str, int, int]: + """`text_lf` with each pair applied whose old text occurs exactly once and whose new text is not there yet. Returns the text, the + pairs applied and the pairs not found (neither the old text once nor the new text present).""" + applied = missing = 0 + for old, new in edits: + if new in text_lf: + continue + if text_lf.count(old) == 1: + text_lf = text_lf.replace(old, new) + applied += 1 + else: + missing += 1 + return text_lf, applied, missing + + +def edited_file(relative: Path, text_lf: str) -> tuple[str, str]: + """The text after the exact-text edits of `relative`, and what was done.""" + edits = EDITS[relative] + text, applied, missing = apply_edits(text_lf, edits) + if not missing: + return text, f"{applied} text change(s)" if applied else "already up to date" + if missing == len(edits): + return text, f"SKIPPED: customised (the 0.1.35 text was not found), so it was left unchanged. See {DOCS_URL}" + skipped = f"SKIPPED {missing} passage(s) that differ from the template text (left as they are). See {DOCS_URL}" + return text, f"{applied} text change(s); {skipped}" if applied else f"the other changes are there; {skipped}" + + +def remove(path: Path, relative: Path) -> str: + """Remove `path` when it is the 0.1.35 template file of `relative`, and say what was done.""" + text_lf = path.read_bytes().decode("utf-8").replace("\r\n", "\n") + previous = (PREVIOUS_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n") + if text_lf != previous: + return f"SKIPPED: customised (not the 0.1.35 template file), so it was kept as the app's own page; the template no longer has it. See {DOCS_URL}" + path.unlink() + return "updated: removed (it was the template file; the App Centre lists the apps)" + + +def update(path: Path, relative: Path) -> str: + data = path.read_bytes().decode("utf-8") + newline = "\r\n" if "\r\n" in data else "\n" + original = data.replace("\r\n", "\n") + text, note = edited_file(relative, original) + if text == original: + return note if note.startswith("SKIPPED") else f"unchanged: {note}" + path.write_bytes(text.replace("\n", newline).encode("utf-8")) + return f"updated: {note}" + + +def migrate(repo_root: Path, context: dict[str, Any]) -> None: + """Apply the 0.1.36 documentation changes (idempotent, surgical, never raises for a customised file, removes only an unchanged file).""" + _ = context + changed = 0 + for relative in FILES: + path = repo_root / relative + if not path.is_file(): + log(f"{relative}: not present in this repository (nothing was created)") + continue + try: + status = remove(path, relative) if relative in REMOVED_FILES else update(path, relative) + except (OSError, UnicodeDecodeError) as exc: + status = f"SKIPPED: {exc}; left unchanged. See {DOCS_URL}" + changed += status.startswith("updated") + log(f"{relative}: {status}") + if changed: + log(f"done: {changed} file(s) changed. The changes reach users with the next release of the app.") + else: + log("done: no repository changes were required.") diff --git a/.tools/docs/use_cases.md b/.template_sync/resources/v0_1_35_to_v0_1_36/previous/.tools/docs/use_cases.md similarity index 100% rename from .tools/docs/use_cases.md rename to .template_sync/resources/v0_1_35_to_v0_1_36/previous/.tools/docs/use_cases.md diff --git a/.tools/docs/README.md b/.tools/docs/README.md index a819601..31305e1 100644 --- a/.tools/docs/README.md +++ b/.tools/docs/README.md @@ -21,7 +21,7 @@ This file temporarily lists all internal LabConstrictor documentation. After you - [Customise the installer images](installer_images.md) - [Describe your app for the App Centre](app_manifest.md) - [Upload external code, and publish it on PyPI (optional)](external_code_upload.md) -- [Expose tools to napari, Fiji and QuPath (experimental)](tools_bridge.md) +- [Expose tools to napari, Fiji and QuPath](tools_bridge.md) ## Keep your app up to date (optional) @@ -33,10 +33,6 @@ This file temporarily lists all internal LabConstrictor documentation. After you - [Write notebooks that run in both Google Colab and JupyterLab](notebook_portability.md) - [Hide code cells in notebooks](code_hiding.md) -## Examples - -- [LabConstrictor use cases](use_cases.md) - ## GitHub management - [GitHub actions/workflows overview](workflow_status.md) diff --git a/.tools/docs/migration_0_1_36.md b/.tools/docs/migration_0_1_36.md new file mode 100644 index 0000000..e1a0b4a --- /dev/null +++ b/.tools/docs/migration_0_1_36.md @@ -0,0 +1,35 @@ +# Template 0.1.36: the plugins are no longer experimental, and the page of examples is gone + +Design note for the 0.1.36 migration (`.template_sync/migrations/v0_1_35_to_v0_1_36.py`). How a change reaches an installed copy is described in [migration_0_1_16.md](migration_0_1_16.md): a new installer is needed, nothing edits an existing install. + +## 1. The problem + +* The napari, Fiji and QuPath plugins that run an app's tools are an implemented way to use an app, but the template still called them experimental: in the title of `tools_bridge.md`, in its entry in the docs README and in its line in `README.md`. +* The "Examples" section of the guides had one page, `use_cases.md`. It listed only VLab4Mic until 0.1.35, and since then it only pointed to the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/), which lists every app. A page that only links elsewhere is not needed. + +## 2. What changes + +| File | Change | +|---|---| +| `.tools/docs/tools_bridge.md` | Title "(optional)" instead of "(optional, experimental)". | +| `.tools/docs/README.md` | The tools entry without "(experimental)"; the "Examples" section is removed. | +| `README.md` | The tools line without "(experimental)"; the "See what others have built" line is removed. | +| `.tools/docs/use_cases.md` | Removed. | + +Whether an app is experimental is a different thing: the `status` field of `labconstrictor-app.yaml` (`Experimental`, `Available` or `Deprecated`) is unchanged. The website publishes `use_cases.md` as `/guides/use-cases/`; it adds a redirect from that address when this version is merged. + +## 3. What the migration does + +Every step is independent and idempotent, never raises for a customised file (the sync pull request is still created) and keeps the line endings of each file. + +* **`use_cases.md`** is removed when it is still the 0.1.35 template file (compared with LF line endings; the frozen copy is in `.template_sync/resources/v0_1_35_to_v0_1_36/previous/`). An app at 0.1.34 gets there through 0.1.35, which first replaces its unchanged page with the 0.1.35 one. A page the app changed is its own and is kept (`SKIPPED`). This is the only file the migration deletes. +* **`tools_bridge.md`, the docs README and `README.md`**: each change replaces one exact piece of 0.1.35 text. A passage where that text is not found is left as it is (`SKIPPED`), and the other changes of the file are still made. An app that keeps its own `use_cases.md` but has the template's README lines loses those links; the log names both files. + +## 4. Adopting it + +Take this template version (the synchronization pull request). Nothing else is needed: the docs change only. + +## 5. What is checked here + +* Tests (`tests/test_template_sync_0_1_36.py`): the page is gone and its frozen copy is the 0.1.35 page; the live files are the 0.1.35 files migrated; no user page or README links `use_cases.md` or calls the plugins experimental; the migration on 0.1.35 files with LF and CRLF line endings, on a customised page and passage, on a repository without the files, on files that are not text, and a second run; the sync from 0.1.35 and the chain from 0.1.34. +* The older tests read a removed file from its frozen copy (`tests/_v0_1_36.py`, `template_bytes`). diff --git a/.tools/docs/tools_bridge.md b/.tools/docs/tools_bridge.md index 7ca94ae..d283aa6 100644 --- a/.tools/docs/tools_bridge.md +++ b/.tools/docs/tools_bridge.md @@ -1,4 +1,4 @@ -# Expose your app's tools to napari, Fiji and QuPath (optional, experimental) +# Expose your app's tools to napari, Fiji and QuPath (optional) If your repository ships Python code (see [Upload external code](external_code_upload.md)), you can declare some of its functions as **tools**. After installation, people can run them in napari, Fiji and QuPath and from the command line, with forms made from the diff --git a/README.md b/README.md index a986abb..1833119 100644 --- a/README.md +++ b/README.md @@ -42,9 +42,8 @@ The same guides, with pictures and a search box, are on the [website](https://ce ## Go further - [List your app in the App Centre](.tools/docs/app_manifest.md) -- [Offer your app's functions in napari, Fiji and QuPath](.tools/docs/tools_bridge.md) (experimental) +- [Offer your app's functions in napari, Fiji and QuPath](.tools/docs/tools_bridge.md) - [Write notebooks that run in both Colab and JupyterLab](.tools/docs/notebook_portability.md) -- [See what others have built](.tools/docs/use_cases.md) - [All guides](.tools/docs/README.md) ## Contributing and questions diff --git a/tests/_v0_1_30.py b/tests/_v0_1_30.py index 2827eac..f806046 100644 --- a/tests/_v0_1_30.py +++ b/tests/_v0_1_30.py @@ -12,6 +12,7 @@ from types import ModuleType from _v0_1_31 import before_0_1_31 +from _v0_1_36 import template_bytes ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_29_to_v0_1_30.py" @@ -46,4 +47,4 @@ def before_0_1_30(relative: Path | str, data: bytes) -> bytes: def live_0_1_29(relative: Path | str) -> bytes: """The live template file at `relative` as template 0.1.29 had it.""" - return before_0_1_30(relative, (ROOT / relative).read_bytes()) + return before_0_1_30(relative, template_bytes(relative)) diff --git a/tests/_v0_1_35.py b/tests/_v0_1_35.py index 942d04f..18d1c70 100644 --- a/tests/_v0_1_35.py +++ b/tests/_v0_1_35.py @@ -11,6 +11,8 @@ from pathlib import Path from types import ModuleType +from _v0_1_36 import before_0_1_36 + ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_34_to_v0_1_35.py" @@ -26,6 +28,7 @@ def _migration() -> ModuleType: def before_0_1_35(relative: Path | str, data: bytes) -> bytes: """`data` (a live template file at `relative`) without the change 0.1.35 made to it; any other file is returned as it is.""" + data = before_0_1_36(relative, data) migration = _migration() relative = Path(relative) if relative not in migration.FILES: diff --git a/tests/_v0_1_36.py b/tests/_v0_1_36.py new file mode 100644 index 0000000..d02675b --- /dev/null +++ b/tests/_v0_1_36.py @@ -0,0 +1,50 @@ +"""Helper of the tests: a live template file as it was before template 0.1.36. + +Template 0.1.36 no longer calls the napari, Fiji and QuPath plugins experimental (tools_bridge.md, the docs README, README.md) and removes +use_cases.md with the "Examples" section of the docs README and the README line that linked it. The tests of the older migrations compare +with the live files: + +* `template_bytes` gives the bytes of a live template file, or of the frozen 0.1.35 copy for a file that 0.1.36 removed; +* `before_0_1_36` gives those bytes without the 0.1.36 edits (the migration's own edits undone). + +The 0.1.36 changes are tested in test_template_sync_0_1_36.py. +""" +from __future__ import annotations + +import importlib.util +from pathlib import Path +from types import ModuleType + +ROOT = Path(__file__).resolve().parents[1] +MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_35_to_v0_1_36.py" + + +def _migration() -> ModuleType: + spec = importlib.util.spec_from_file_location("migration_0_1_36_for_older_tests", MIGRATION_PATH) + if spec is None or spec.loader is None: + raise RuntimeError(f"Unable to load {MIGRATION_PATH}") + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +def template_bytes(relative: Path | str) -> bytes: + """The live template file at `relative`; for a file 0.1.36 removed, the 0.1.35 template file it removed.""" + relative = Path(relative) + if relative in _migration().REMOVED_FILES and not (ROOT / relative).exists(): + return (_migration().PREVIOUS_ROOT / relative).read_bytes() + return (ROOT / relative).read_bytes() + + +def before_0_1_36(relative: Path | str, data: bytes) -> bytes: + """`data` (a live template file at `relative`) without the edits 0.1.36 made to it; any other file is returned as it is.""" + migration = _migration() + relative = Path(relative) + if relative not in migration.EDITS: + return data + text = data.decode("utf-8") + newline = "\r\n" if "\r\n" in text else "\n" + text = text.replace("\r\n", "\n") + for old, new in reversed(migration.EDITS[relative]): + text = text.replace(new, old, 1) + return text.replace("\n", newline).encode("utf-8") diff --git a/tests/test_template_sync_0_1_29.py b/tests/test_template_sync_0_1_29.py index c7b3a15..dea02ac 100644 --- a/tests/test_template_sync_0_1_29.py +++ b/tests/test_template_sync_0_1_29.py @@ -15,6 +15,7 @@ from _v0_1_29 import before_0_1_29 from _v0_1_30 import live_0_1_29 +from _v0_1_36 import template_bytes ROOT = Path(__file__).resolve().parents[1] @@ -76,7 +77,7 @@ def setUp(self) -> None: for relative in MIGRATION.EDITS: target = self.repo / relative target.parent.mkdir(parents=True, exist_ok=True) - data = index_of_0_1_28() if relative == INDEX else before_0_1_29(relative, (ROOT / relative).read_bytes()) + data = index_of_0_1_28() if relative == INDEX else before_0_1_29(relative, template_bytes(relative)) target.write_bytes(data) def tearDown(self) -> None: diff --git a/tests/test_template_sync_0_1_30.py b/tests/test_template_sync_0_1_30.py index c92fe99..caa707e 100644 --- a/tests/test_template_sync_0_1_30.py +++ b/tests/test_template_sync_0_1_30.py @@ -16,6 +16,7 @@ from _v0_1_30 import before_0_1_30 from _v0_1_32 import before_0_1_32 +from _v0_1_36 import template_bytes ROOT = Path(__file__).resolve().parents[1] @@ -46,7 +47,7 @@ def lf(path: Path) -> str: def at_0_1_31(relative: Path) -> bytes: """The live template file without the later changes of 0.1.32 (tools_bridge.md and install.md: tests/_v0_1_32.py).""" - return before_0_1_32(relative, (ROOT / relative).read_bytes()) + return before_0_1_32(relative, template_bytes(relative)) class TemplateTests(unittest.TestCase): @@ -82,7 +83,7 @@ class MigrationTests(unittest.TestCase): def setUp(self) -> None: self.repo = Path(tempfile.mkdtemp(prefix="lc_0_1_30_")) for relative in TEMPLATE_FILES: - self.put(relative, before_0_1_30(relative, (ROOT / relative).read_bytes())) + self.put(relative, before_0_1_30(relative, template_bytes(relative))) self.put(MIGRATION.APP_MANIFEST, APP_MANIFEST_BEFORE.encode("utf-8")) self.put(MIGRATION.PROJECT_FILE, PROJECT_FILE_BEFORE.encode("utf-8")) diff --git a/tests/test_template_sync_0_1_35.py b/tests/test_template_sync_0_1_35.py index 8d9c496..4cd45b6 100644 --- a/tests/test_template_sync_0_1_35.py +++ b/tests/test_template_sync_0_1_35.py @@ -16,6 +16,7 @@ from types import ModuleType from _v0_1_35 import before_0_1_35 +from _v0_1_36 import before_0_1_36, template_bytes ROOT = Path(__file__).resolve().parents[1] @@ -40,9 +41,14 @@ def lf(path: Path) -> str: return path.read_bytes().decode("utf-8").replace("\r\n", "\n") +def live(relative: Path) -> bytes: + """The template file as 0.1.35 left it (later changes undone, tests/_v0_1_36.py and newer; a file removed later is its frozen copy).""" + return before_0_1_36(relative, template_bytes(relative)) + + def old(relative: Path) -> bytes: """The 0.1.34 file: the live file without the 0.1.35 change.""" - return before_0_1_35(relative, (ROOT / relative).read_bytes()) + return before_0_1_35(relative, template_bytes(relative)) def user_pages() -> list[Path]: @@ -75,15 +81,15 @@ def test_the_design_note_exists_and_the_migration_links_it(self) -> None: def test_the_resources_are_the_live_page_and_the_0_1_34_one(self) -> None: for relative in MIGRATION.WHOLE_FILES: with self.subTest(file=str(relative)): - self.assertEqual((MIGRATION.RESOURCE_ROOT / relative).read_bytes(), (ROOT / relative).read_bytes()) - self.assertNotEqual(lf(MIGRATION.PREVIOUS_ROOT / relative), lf(ROOT / relative)) + self.assertEqual((MIGRATION.RESOURCE_ROOT / relative).read_bytes(), live(relative)) + self.assertNotEqual(lf(MIGRATION.PREVIOUS_ROOT / relative), live(relative).decode("utf-8")) def test_the_live_files_are_the_0_1_34_files_migrated(self) -> None: for relative in MIGRATION.EDITS: with self.subTest(file=str(relative)): text, applied, missing = MIGRATION.apply_edits(old(relative).decode("utf-8"), MIGRATION.EDITS[relative]) self.assertEqual((applied, missing), (len(MIGRATION.EDITS[relative]), 0)) - self.assertEqual(text, lf(ROOT / relative)) + self.assertEqual(text, live(relative).decode("utf-8")) def test_install_says_how_to_uninstall_on_each_system(self) -> None: text = lf(ROOT / MIGRATION.INSTALL_DOC) @@ -107,11 +113,11 @@ def test_no_user_page_links_to_the_download_stub_for_uninstalling_or_to_authorin with self.subTest(file=path.name): self.assertNotIn("[uninstalling guide](./download_executable.md)", text) self.assertNotIn(MIGRATION.AUTHORING_ON_GITHUB, text) - self.assertEqual(lf(ROOT / MIGRATION.TOOLS_DOC).count(f"]({MIGRATION.WRITING_TOOLS})"), 2) + self.assertEqual(live(MIGRATION.TOOLS_DOC).decode("utf-8").count(f"]({MIGRATION.WRITING_TOOLS})"), 2) self.assertIn("](install.md#uninstall-an-app)", lf(ROOT / MIGRATION.TROUBLESHOOTING_DOC)) def test_use_cases_links_to_the_app_centre(self) -> None: - text = lf(ROOT / MIGRATION.USE_CASES_DOC) + text = live(MIGRATION.USE_CASES_DOC).decode("utf-8") self.assertIn(f"]({SITE}apps/)", text) self.assertNotIn("## VLab4Mic", text) @@ -127,7 +133,7 @@ def test_user_page_headings_follow_the_website_style(self) -> None: def test_the_links_of_the_changed_pages_resolve(self) -> None: for relative in MIGRATION.FILES: - for target, anchor in re.findall(r"\]\(([^)#\s]*)(?:#([^)\s]*))?\)", lf(ROOT / relative)): + for target, anchor in re.findall(r"\]\(([^)#\s]*)(?:#([^)\s]*))?\)", live(relative).decode("utf-8")): if "://" in target: continue with self.subTest(file=str(relative), target=target, anchor=anchor): @@ -161,11 +167,11 @@ def run_migration(self) -> str: def test_an_app_of_0_1_34_gets_the_template_files_and_a_second_run_changes_nothing(self) -> None: for relative in MIGRATION.FILES: - self.assertNotEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes(), relative) + self.assertNotEqual((self.repo / relative).read_bytes(), live(relative), relative) log = self.run_migration() for relative in MIGRATION.FILES: with self.subTest(file=str(relative)): - self.assertEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes()) + self.assertEqual((self.repo / relative).read_bytes(), live(relative)) self.assertIn(f"done: {len(MIGRATION.FILES)} file(s) changed", log) self.assertNotIn("SKIPPED", log) again = self.run_migration() @@ -180,7 +186,7 @@ def test_crlf_is_kept(self) -> None: with self.subTest(file=str(relative)): raw = (self.repo / relative).read_bytes() self.assertNotIn(b"\n", raw.replace(b"\r\n", b"")) - self.assertEqual(raw.replace(b"\r\n", b"\n"), (ROOT / relative).read_bytes()) + self.assertEqual(raw.replace(b"\r\n", b"\n"), live(relative)) def test_a_customised_use_cases_page_is_skipped(self) -> None: page = self.put(MIGRATION.USE_CASES_DOC, old(MIGRATION.USE_CASES_DOC) + b"\n## Our own app\n") @@ -229,7 +235,7 @@ def test_the_sync_script_runs_the_migration_from_0_1_34(self) -> None: self.assertIn("[migration 0.1.35]", result.stdout) for relative in MIGRATION.FILES: with self.subTest(file=str(relative)): - self.assertEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes()) + self.assertEqual((self.repo / relative).read_bytes(), live(relative)) again = subprocess.run(command, capture_output=True, text=True, env=env, check=False) self.assertIn("no repository changes were required", again.stdout) diff --git a/tests/test_template_sync_0_1_36.py b/tests/test_template_sync_0_1_36.py new file mode 100644 index 0000000..6ebe41e --- /dev/null +++ b/tests/test_template_sync_0_1_36.py @@ -0,0 +1,222 @@ +"""Tests of the 0.1.36 migration: the plugins are no longer called experimental, and use_cases.md (the "Examples" section) is removed.""" +from __future__ import annotations + +import importlib.util +import os +import re +import shutil +import subprocess +import sys +import tempfile +import unittest +from contextlib import redirect_stdout +from io import StringIO +from pathlib import Path +from types import ModuleType + +from _v0_1_36 import before_0_1_36, template_bytes + + +ROOT = Path(__file__).resolve().parents[1] +MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_35_to_v0_1_36.py" +SYNC_PATH = ROOT / ".template_sync/sync.py" +DOCS = ROOT / ".tools/docs" + + +def load(path: Path, name: str) -> ModuleType: + spec = importlib.util.spec_from_file_location(name, path) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +MIGRATION = load(MIGRATION_PATH, "migration_0_1_36") + + +def lf(path: Path) -> str: + return path.read_bytes().decode("utf-8").replace("\r\n", "\n") + + +def old(relative: Path) -> bytes: + """The 0.1.35 file: the live file without the 0.1.36 change (the frozen copy for a removed file).""" + return before_0_1_36(relative, template_bytes(relative)) + + +def user_pages() -> list[Path]: + """The user-facing pages of .tools/docs (the migration_*.md design notes are history) and the README.""" + return [*sorted(path for path in DOCS.glob("*.md") if not path.name.startswith("migration_")), ROOT / "README.md"] + + +class TemplateTests(unittest.TestCase): + def test_the_manifest_lists_the_migration_and_the_new_version(self) -> None: + text = lf(ROOT / ".template_sync/manifest.yaml") + self.assertRegex(text, r"template_version: 0\.1\.(3[6-9]|[4-9][0-9])\b") + self.assertIn("script: migrations/v0_1_35_to_v0_1_36.py", text) + + def test_chains_from_older_versions_reach_0_1_36(self) -> None: + sync = load(SYNC_PATH, "sync_for_0_1_36") + manifest = sync.parse_manifest(ROOT / ".template_sync/manifest.yaml") + for start in ("0.0.0", "0.1.16", "0.1.34", "0.1.35"): + self.assertEqual(sync.resolve_migration_chain(manifest["migrations"], start, "0.1.36")[-1]["to"], "0.1.36", start) + + def test_the_design_note_exists_and_the_migration_links_it(self) -> None: + self.assertTrue((DOCS / "migration_0_1_36.md").is_file()) + self.assertIn(".tools/docs/migration_0_1_36.md", MIGRATION.DOCS_URL) + self.assertNotIn("migration_0_1_36.md", lf(DOCS / "README.md"), "the docs README does not list design notes") + + def test_the_removed_page_is_gone_and_its_frozen_copy_is_the_0_1_35_page(self) -> None: + for relative in MIGRATION.REMOVED_FILES: + with self.subTest(file=str(relative)): + self.assertFalse((ROOT / relative).exists()) + self.assertIn("App Centre", lf(MIGRATION.PREVIOUS_ROOT / relative)) + + def test_the_live_files_are_the_0_1_35_files_migrated(self) -> None: + for relative in MIGRATION.EDITS: + with self.subTest(file=str(relative)): + text, applied, missing = MIGRATION.apply_edits(old(relative).decode("utf-8"), MIGRATION.EDITS[relative]) + self.assertEqual((applied, missing), (len(MIGRATION.EDITS[relative]), 0)) + self.assertEqual(text, lf(ROOT / relative)) + + def test_no_user_page_links_use_cases_or_calls_the_plugins_experimental(self) -> None: + for path in user_pages(): + text = lf(path) + with self.subTest(file=path.name): + self.assertNotIn("use_cases.md", text) + self.assertNotIn("## Examples", text) + for line in text.splitlines(): + if re.search(r"experimental|prototype", line, re.IGNORECASE): + # an app's maturity (`status: Experimental` of labconstrictor-app.yaml) is the app's own word, not the plugins' + self.assertIn("Experimental`", line) + + def test_the_relative_links_of_the_changed_pages_resolve(self) -> None: + for relative in MIGRATION.EDITS: + for target in re.findall(r"\]\(([^)#\s]+)(?:#[^)]*)?\)", lf(ROOT / relative)): + if "://" in target: + continue + with self.subTest(file=str(relative), target=target): + self.assertTrue(((ROOT / relative).parent / target).resolve().exists()) + + +class MigrationTests(unittest.TestCase): + def setUp(self) -> None: + self.repo = Path(tempfile.mkdtemp(prefix="lc_0_1_36_")) + for relative in MIGRATION.FILES: + self.put(relative, old(relative)) + + def tearDown(self) -> None: + shutil.rmtree(self.repo, ignore_errors=True) + + def put(self, relative: Path, data: bytes) -> Path: + target = self.repo / relative + target.parent.mkdir(parents=True, exist_ok=True) + target.write_bytes(data) + return target + + def run_migration(self) -> str: + out = StringIO() + with redirect_stdout(out): + MIGRATION.migrate(self.repo, {}) + return out.getvalue() + + def assert_template_state(self) -> None: + for relative in MIGRATION.REMOVED_FILES: + self.assertFalse((self.repo / relative).exists(), relative) + for relative in MIGRATION.EDITS: + with self.subTest(file=str(relative)): + self.assertEqual((self.repo / relative).read_bytes().replace(b"\r\n", b"\n"), (ROOT / relative).read_bytes()) + + def test_an_app_of_0_1_35_gets_the_template_files_and_a_second_run_changes_nothing(self) -> None: + log = self.run_migration() + self.assert_template_state() + self.assertIn(f"{MIGRATION.USE_CASES_DOC}: updated: removed", log) + self.assertIn(f"done: {len(MIGRATION.FILES)} file(s) changed", log) + self.assertNotIn("SKIPPED", log) + again = self.run_migration() + self.assertIn("no repository changes were required", again) + self.assertIn(f"{MIGRATION.USE_CASES_DOC}: not present in this repository (nothing was created)", again) + self.assertNotIn("SKIPPED", again) + + def test_crlf_is_kept_and_a_crlf_copy_of_the_page_is_removed(self) -> None: + for relative in MIGRATION.FILES: + self.put(relative, old(relative).replace(b"\n", b"\r\n")) + self.run_migration() + self.assert_template_state() + for relative in MIGRATION.EDITS: + with self.subTest(file=str(relative)): + self.assertNotIn(b"\n", (self.repo / relative).read_bytes().replace(b"\r\n", b"")) + + def test_a_customised_use_cases_page_is_kept(self) -> None: + page = self.put(MIGRATION.USE_CASES_DOC, old(MIGRATION.USE_CASES_DOC) + b"\n## Our own app\n") + before = page.read_bytes() + log = self.run_migration() + self.assertIn(f"{MIGRATION.USE_CASES_DOC}: SKIPPED: customised (not the 0.1.35 template file)", log) + self.assertEqual(page.read_bytes(), before) + + def test_the_0_1_34_page_is_not_removed_by_this_step_alone(self) -> None: + """An app at 0.1.34 reaches 0.1.36 through 0.1.35, which replaces the unchanged page first; on its own this step keeps it.""" + frozen = ROOT / ".template_sync/resources/v0_1_34_to_v0_1_35/previous" / MIGRATION.USE_CASES_DOC + self.put(MIGRATION.USE_CASES_DOC, frozen.read_bytes()) + self.assertIn("SKIPPED", self.run_migration()) + self.assertTrue((self.repo / MIGRATION.USE_CASES_DOC).exists()) + + def test_a_customised_passage_is_skipped_and_the_others_change(self) -> None: + index = self.put(MIGRATION.DOCS_INDEX, b"# Our guides\n\nOur own text.\n") + log = self.run_migration() + self.assertIn(f"{MIGRATION.DOCS_INDEX}: SKIPPED: customised", log) + self.assertEqual(index.read_bytes(), b"# Our guides\n\nOur own text.\n") + text = old(MIGRATION.DOCS_INDEX).decode("utf-8").replace("- [LabConstrictor use cases](use_cases.md)\n", "- [Our examples](use_cases.md)\n") + index.write_text(text, encoding="utf-8", newline="\n") + log = self.run_migration() + self.assertIn(f"{MIGRATION.DOCS_INDEX}: updated: 1 text change(s); SKIPPED 1 passage(s)", log) + changed = lf(index) + self.assertIn("- [Our examples](use_cases.md)\n", changed) + self.assertIn("- [Expose tools to napari, Fiji and QuPath](tools_bridge.md)\n", changed) + + def test_missing_files_are_not_created(self) -> None: + for relative in MIGRATION.FILES: + (self.repo / relative).unlink() + log = self.run_migration() + for relative in MIGRATION.FILES: + self.assertIn(f"{relative}: not present in this repository (nothing was created)", log) + self.assertEqual([p for p in self.repo.rglob("*") if p.is_file()], []) + + def test_a_file_that_is_not_text_is_skipped_and_kept(self) -> None: + for relative in (MIGRATION.USE_CASES_DOC, MIGRATION.ROOT_README): + self.put(relative, b"\xff\xfe not utf-8") + log = self.run_migration() + for relative in (MIGRATION.USE_CASES_DOC, MIGRATION.ROOT_README): + with self.subTest(file=str(relative)): + self.assertIn(f"{relative}: SKIPPED", log) + self.assertEqual((self.repo / relative).read_bytes(), b"\xff\xfe not utf-8") + + def test_the_sync_script_runs_the_migration_from_0_1_35(self) -> None: + shutil.copytree(ROOT / ".template_sync", self.repo / ".template_sync") + # sync.py refuses a target other than the manifest version: pin the copy to 0.1.36 (later templates add migrations). + manifest = self.repo / ".template_sync/manifest.yaml" + manifest.write_text(re.sub(r"template_version: [0-9.]+", "template_version: 0.1.36", manifest.read_text(encoding="utf-8")), encoding="utf-8") + command = [sys.executable, str(self.repo / ".template_sync/sync.py"), "--from-version", "0.1.35", "--to-version", "0.1.36", "--repository-root", str(self.repo)] + env = {key: value for key, value in os.environ.items() if key != "PYTHONPATH"} + result = subprocess.run(command, capture_output=True, text=True, env=env, check=False) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("[migration 0.1.36]", result.stdout) + self.assert_template_state() + again = subprocess.run(command, capture_output=True, text=True, env=env, check=False) + self.assertIn("no repository changes were required", again.stdout) + + def test_the_sync_chain_from_0_1_34_removes_an_unchanged_page(self) -> None: + """0.1.35 replaces the 0.1.34 page with the App Centre page, then 0.1.36 removes it.""" + shutil.copytree(ROOT / ".template_sync", self.repo / ".template_sync") + frozen = ROOT / ".template_sync/resources/v0_1_34_to_v0_1_35/previous" / MIGRATION.USE_CASES_DOC + self.put(MIGRATION.USE_CASES_DOC, frozen.read_bytes()) + manifest = self.repo / ".template_sync/manifest.yaml" + manifest.write_text(re.sub(r"template_version: [0-9.]+", "template_version: 0.1.36", manifest.read_text(encoding="utf-8")), encoding="utf-8") + command = [sys.executable, str(self.repo / ".template_sync/sync.py"), "--from-version", "0.1.34", "--to-version", "0.1.36", "--repository-root", str(self.repo)] + env = {key: value for key, value in os.environ.items() if key != "PYTHONPATH"} + result = subprocess.run(command, capture_output=True, text=True, env=env, check=False) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertFalse((self.repo / MIGRATION.USE_CASES_DOC).exists(), result.stdout) + + +if __name__ == "__main__": + unittest.main()