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()