Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .template_sync/manifest.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
template_version: 0.1.35
template_version: 0.1.36
migrations:
- from: 0.0.0
to: 0.0.1
Expand Down Expand Up @@ -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
133 changes: 133 additions & 0 deletions .template_sync/migrations/v0_1_35_to_v0_1_36.py
Original file line number Diff line number Diff line change
@@ -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.")
File renamed without changes.
6 changes: 1 addition & 5 deletions .tools/docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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)
Expand Down
35 changes: 35 additions & 0 deletions .tools/docs/migration_0_1_36.md
Original file line number Diff line number Diff line change
@@ -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`).
2 changes: 1 addition & 1 deletion .tools/docs/tools_bridge.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
3 changes: 1 addition & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion tests/_v0_1_30.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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))
3 changes: 3 additions & 0 deletions tests/_v0_1_35.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand All @@ -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:
Expand Down
50 changes: 50 additions & 0 deletions tests/_v0_1_36.py
Original file line number Diff line number Diff line change
@@ -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")
3 changes: 2 additions & 1 deletion tests/test_template_sync_0_1_29.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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:
Expand Down
5 changes: 3 additions & 2 deletions tests/test_template_sync_0_1_30.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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"))

Expand Down
Loading
Loading