diff --git a/.template_sync/manifest.yaml b/.template_sync/manifest.yaml
index 92285f2..153a7af 100644
--- a/.template_sync/manifest.yaml
+++ b/.template_sync/manifest.yaml
@@ -1,4 +1,4 @@
-template_version: 0.1.38
+template_version: 0.1.39
migrations:
- from: 0.0.0
to: 0.0.1
@@ -120,3 +120,6 @@ migrations:
- from: 0.1.37
to: 0.1.38
script: migrations/v0_1_37_to_v0_1_38.py
+ - from: 0.1.38
+ to: 0.1.39
+ script: migrations/v0_1_38_to_v0_1_39.py
diff --git a/.template_sync/migrations/v0_1_38_to_v0_1_39.py b/.template_sync/migrations/v0_1_38_to_v0_1_39.py
new file mode 100644
index 0000000..14a8384
--- /dev/null
+++ b/.template_sync/migrations/v0_1_38_to_v0_1_39.py
@@ -0,0 +1,87 @@
+"""Template 0.1.38 -> 0.1.39: the installer intros say that a release builds only the systems the app lists.
+
+Design note: https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_39.md
+
+before_getting_started.md and executable_creation.md said that a release builds installers for Windows, macOS and Linux. It builds only
+the systems listed under `distribution.platforms` in labconstrictor-app.yaml (all of them when the list is missing); both intros now say so
+and link the manifest guide.
+
+What this changes in an app repository: each file in FILES is replaced by the 0.1.39 page when it is still the 0.1.38 template file
+(compared with LF line endings; the file keeps its own line endings). A file the app changed itself stays as it is (SKIPPED, with a note of
+what to change by hand). A missing file is not created, and nothing is deleted. 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_39.md"
+TAG = "[migration 0.1.39]"
+RESOURCE_ROOT = Path(__file__).resolve().parents[1] / "resources" / "v0_1_38_to_v0_1_39"
+PREVIOUS_ROOT = RESOURCE_ROOT / "previous"
+
+DOCS = Path(".tools/docs")
+
+# Files replaced whole, only when they are the 0.1.38 template file (compared with LF line endings).
+FILES = (DOCS / "before_getting_started.md", DOCS / "executable_creation.md")
+
+# What to change by hand in a customised file (added to the SKIPPED note).
+BY_HAND = (
+ "where the page says a release builds installers for Windows, macOS and Linux, add that it builds only the systems listed under "
+ "distribution.platforms in labconstrictor-app.yaml (link app_manifest.md#distribution-how-people-get-the-app)"
+)
+
+
+def log(message: str) -> None:
+ print(f"{TAG} {message}")
+
+
+def lf_text(path: Path) -> str:
+ return path.read_bytes().decode("utf-8").replace("\r\n", "\n")
+
+
+def replaced_file(relative: Path, text_lf: str) -> tuple[str, str]:
+ """The 0.1.39 text of `relative` for the app's `text_lf`, and what was done. The text is unchanged when it is not the 0.1.38 template file."""
+ new = lf_text(RESOURCE_ROOT / relative)
+ previous = lf_text(PREVIOUS_ROOT / relative)
+ if text_lf == new:
+ return text_lf, "already up to date"
+ if text_lf == previous:
+ return new, "replaced by the 0.1.39 page"
+ return text_lf, (
+ "SKIPPED: customised (not the 0.1.38 template file), so it was left unchanged; compare it with the template's page. "
+ f"By hand: {BY_HAND}. See {DOCS_URL}"
+ )
+
+
+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 = replaced_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.39 documentation changes (idempotent, never raises for a customised file, creates and deletes nothing)."""
+ _ = 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 = 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/.template_sync/resources/v0_1_38_to_v0_1_39/.tools/docs/before_getting_started.md b/.template_sync/resources/v0_1_38_to_v0_1_39/.tools/docs/before_getting_started.md
new file mode 100644
index 0000000..16d81f9
--- /dev/null
+++ b/.template_sync/resources/v0_1_38_to_v0_1_39/.tools/docs/before_getting_started.md
@@ -0,0 +1,53 @@
+# Before getting started with LabConstrictor
+
+What LabConstrictor does, and what you need before you create your repository.
+
+## LabConstrictor in a nutshell
+
+LabConstrictor is a GitHub template repository that turns your Jupyter notebooks into a desktop app that people install with one installer. GitHub Actions workflows in your repository do the building.
+
+### Easy configuration
+
+A web form sets up your repository (name, version, description, images) and uploads your notebooks with their requirements. You do not edit the workflows yourself.
+
+### Cross-platform installers
+
+Publishing a release builds installers with [conda constructor](https://github.com/conda/constructor): Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app).
+
+### Environment management
+
+Each notebook comes with a `requirements.yaml` file that lists its packages. The workflows merge the requirements of all notebooks and fix every package version, so each installation of a release gets the same packages. Helper notebooks generate and check these files for you.
+
+### Version control
+
+The first cell of each notebook checks its version. The app's Welcome notebook shows when a newer version of a notebook exists and updates it.
+
+### User-friendly experience
+
+The installed app opens JupyterLab with a Welcome notebook that lists your notebooks. Code cells can be hidden and run with a play button, so a notebook looks like a simple app. Your repository can be public or private; a private repository cannot be listed in the App Centre.
+
+### Offline usage
+
+Once installed, the app runs without internet access, unless your notebooks need it.
+
+## LabConstrictor requirements
+
+- **A GitHub account**, to create your repository from the template.
+- **Your Jupyter notebooks.**
+- **A Python environment where your notebooks run without errors**, on your computer or in Google Colab. You use it to generate the requirements files. You can also write these files by hand.
+- **A GitHub personal access token** (classic, with the **repo** scope), which the web forms use to open pull requests in your repository: see [Generate a GitHub personal access token](personal_access_token.md).
+- **Optional: images** (logo, banner, header) to brand the installer: see [Customise the installer images](installer_images.md).
+
+Next: [Create your repository](create_repository.md).
+
+
+---
+
+
+
+← Previous
+[🏠 Home](README.md)
+[Next →](create_repository.md)
+
+
+
diff --git a/.template_sync/resources/v0_1_38_to_v0_1_39/.tools/docs/executable_creation.md b/.template_sync/resources/v0_1_38_to_v0_1_39/.tools/docs/executable_creation.md
new file mode 100644
index 0000000..89516a0
--- /dev/null
+++ b/.template_sync/resources/v0_1_38_to_v0_1_39/.tools/docs/executable_creation.md
@@ -0,0 +1,56 @@
+# Create installer files
+
+Publishing a GitHub release builds the installers of your app and attaches them to the release: Windows (`.exe`), macOS (`.pkg`, Apple Silicon and Intel) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app).
+
+## What you need
+
+- At least one notebook uploaded and merged: see [Add or update a notebook](notebook_upload.md).
+- A version number for the release, in the form `MAJOR.MINOR.PATCH` (for example `0.0.1`).
+
+## Check before you release
+
+- **The systems you build for.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml`, or every system when that line is missing: see [`distribution` in Describe your app](app_manifest.md#distribution-how-people-get-the-app). Check that the list holds every system your app should run on.
+- **Every workflow run is green.** Open the **Actions** tab of your repository. No workflow may still be running: a release started while another workflow runs may build from files that are about to change. The latest run of each workflow must have a green tick, not only have finished: a red cross means its changes, for example your notebook's requirements, did not make it into the repository ([how to read a run](workflow_status.md)).
+
+## 1. Draft a new release
+
+1. Go to your repository's main page.
+2. Click **Releases** (in the right sidebar).
+3. Click **Create a new release** and fill in:
+ - **Tag**: click **Create a new tag** and enter the version number, for example `0.0.1`. It must have the form `MAJOR.MINOR.PATCH` (`1.0.0`, `1.2.3`). A `v` in front (`v1.0.0`) also works: the installers are named with the version without it.
+ - **Release title**: for example `Initial release`.
+ - **Description** (optional): what is new in this release.
+
+## 2. Publish the release
+
+Click **Publish release**. This starts the workflow **Build Release Installers**. It sets the version in your repository's files, then builds one installer per system.
+
+## Check that it worked
+
+- In the **Actions** tab, the run of **Build Release Installers** has a green tick ([how to read a run](workflow_status.md)).
+- Open your repository's **Releases** page and the release you published: its **Assets** list holds the installers, named `--` (for example `MyApp-0.0.1-Windows-x86_64.exe`).
+- `.tools/docs/download_executable.md` in your repository now has download buttons for this release.
+
+## If something does not work
+
+- **The run stops at "check_placeholders.py", "Installers to build" or with conflicting package versions.** See [Troubleshooting repository setup](troubleshooting.md): each of these has its own section.
+- **Another step failed.** Open the failed run and read the log of the red step ([how](workflow_status.md)). After you fix the problem, delete the release and its tag, then publish the release again.
+- **An installer is missing for one system.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml` (all of them when it is not set): see [Describe your app for the App Centre](app_manifest.md).
+
+## 3. After the release
+
+- Try your installer yourself: [Install an app](install.md), then [Open and use an app](notebook_usage.md).
+- List your app in the App Centre: [Describe your app for the App Centre](app_manifest.md), then [Submit your app](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/).
+- Receive future template improvements as pull requests: [Keep your app up to date](template_synchronization.md).
+
+
+---
+
+
+
+[← Previous](notebook_upload.md)
+[🏠 Home](README.md)
+[Next →](installer_images.md)
+
+
+
diff --git a/.template_sync/resources/v0_1_38_to_v0_1_39/previous/.tools/docs/before_getting_started.md b/.template_sync/resources/v0_1_38_to_v0_1_39/previous/.tools/docs/before_getting_started.md
new file mode 100644
index 0000000..cbbed46
--- /dev/null
+++ b/.template_sync/resources/v0_1_38_to_v0_1_39/previous/.tools/docs/before_getting_started.md
@@ -0,0 +1,53 @@
+# Before getting started with LabConstrictor
+
+What LabConstrictor does, and what you need before you create your repository.
+
+## LabConstrictor in a nutshell
+
+LabConstrictor is a GitHub template repository that turns your Jupyter notebooks into a desktop app that people install with one installer. GitHub Actions workflows in your repository do the building.
+
+### Easy configuration
+
+A web form sets up your repository (name, version, description, images) and uploads your notebooks with their requirements. You do not edit the workflows yourself.
+
+### Cross-platform installers
+
+Publishing a release builds installers for Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`) with [conda constructor](https://github.com/conda/constructor).
+
+### Environment management
+
+Each notebook comes with a `requirements.yaml` file that lists its packages. The workflows merge the requirements of all notebooks and fix every package version, so each installation of a release gets the same packages. Helper notebooks generate and check these files for you.
+
+### Version control
+
+The first cell of each notebook checks its version. The app's Welcome notebook shows when a newer version of a notebook exists and updates it.
+
+### User-friendly experience
+
+The installed app opens JupyterLab with a Welcome notebook that lists your notebooks. Code cells can be hidden and run with a play button, so a notebook looks like a simple app. Your repository can be public or private; a private repository cannot be listed in the App Centre.
+
+### Offline usage
+
+Once installed, the app runs without internet access, unless your notebooks need it.
+
+## LabConstrictor requirements
+
+- **A GitHub account**, to create your repository from the template.
+- **Your Jupyter notebooks.**
+- **A Python environment where your notebooks run without errors**, on your computer or in Google Colab. You use it to generate the requirements files. You can also write these files by hand.
+- **A GitHub personal access token** (classic, with the **repo** scope), which the web forms use to open pull requests in your repository: see [Generate a GitHub personal access token](personal_access_token.md).
+- **Optional: images** (logo, banner, header) to brand the installer: see [Customise the installer images](installer_images.md).
+
+Next: [Create your repository](create_repository.md).
+
+
+---
+
+
+
+← Previous
+[🏠 Home](README.md)
+[Next →](create_repository.md)
+
+
+
diff --git a/.template_sync/resources/v0_1_38_to_v0_1_39/previous/.tools/docs/executable_creation.md b/.template_sync/resources/v0_1_38_to_v0_1_39/previous/.tools/docs/executable_creation.md
new file mode 100644
index 0000000..5194968
--- /dev/null
+++ b/.template_sync/resources/v0_1_38_to_v0_1_39/previous/.tools/docs/executable_creation.md
@@ -0,0 +1,56 @@
+# Create installer files
+
+Publishing a GitHub release builds the installers of your app for Windows (`.exe`), macOS (`.pkg`, Apple Silicon and Intel) and Linux (`.sh`) and attaches them to the release.
+
+## What you need
+
+- At least one notebook uploaded and merged: see [Add or update a notebook](notebook_upload.md).
+- A version number for the release, in the form `MAJOR.MINOR.PATCH` (for example `0.0.1`).
+
+## Check before you release
+
+- **The systems you build for.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml`, or every system when that line is missing: see [`distribution` in Describe your app](app_manifest.md#distribution-how-people-get-the-app). Check that the list holds every system your app should run on.
+- **Every workflow run is green.** Open the **Actions** tab of your repository. No workflow may still be running: a release started while another workflow runs may build from files that are about to change. The latest run of each workflow must have a green tick, not only have finished: a red cross means its changes, for example your notebook's requirements, did not make it into the repository ([how to read a run](workflow_status.md)).
+
+## 1. Draft a new release
+
+1. Go to your repository's main page.
+2. Click **Releases** (in the right sidebar).
+3. Click **Create a new release** and fill in:
+ - **Tag**: click **Create a new tag** and enter the version number, for example `0.0.1`. It must have the form `MAJOR.MINOR.PATCH` (`1.0.0`, `1.2.3`). A `v` in front (`v1.0.0`) also works: the installers are named with the version without it.
+ - **Release title**: for example `Initial release`.
+ - **Description** (optional): what is new in this release.
+
+## 2. Publish the release
+
+Click **Publish release**. This starts the workflow **Build Release Installers**. It sets the version in your repository's files, then builds one installer per system.
+
+## Check that it worked
+
+- In the **Actions** tab, the run of **Build Release Installers** has a green tick ([how to read a run](workflow_status.md)).
+- Open your repository's **Releases** page and the release you published: its **Assets** list holds the installers, named `--` (for example `MyApp-0.0.1-Windows-x86_64.exe`).
+- `.tools/docs/download_executable.md` in your repository now has download buttons for this release.
+
+## If something does not work
+
+- **The run stops at "check_placeholders.py", "Installers to build" or with conflicting package versions.** See [Troubleshooting repository setup](troubleshooting.md): each of these has its own section.
+- **Another step failed.** Open the failed run and read the log of the red step ([how](workflow_status.md)). After you fix the problem, delete the release and its tag, then publish the release again.
+- **An installer is missing for one system.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml` (all of them when it is not set): see [Describe your app for the App Centre](app_manifest.md).
+
+## 3. After the release
+
+- Try your installer yourself: [Install an app](install.md), then [Open and use an app](notebook_usage.md).
+- List your app in the App Centre: [Describe your app for the App Centre](app_manifest.md), then [Submit your app](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/).
+- Receive future template improvements as pull requests: [Keep your app up to date](template_synchronization.md).
+
+
+---
+
+
+
+[← Previous](notebook_upload.md)
+[🏠 Home](README.md)
+[Next →](installer_images.md)
+
+
+
diff --git a/.tools/docs/before_getting_started.md b/.tools/docs/before_getting_started.md
index cbbed46..16d81f9 100644
--- a/.tools/docs/before_getting_started.md
+++ b/.tools/docs/before_getting_started.md
@@ -12,7 +12,7 @@ A web form sets up your repository (name, version, description, images) and uplo
### Cross-platform installers
-Publishing a release builds installers for Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`) with [conda constructor](https://github.com/conda/constructor).
+Publishing a release builds installers with [conda constructor](https://github.com/conda/constructor): Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app).
### Environment management
diff --git a/.tools/docs/executable_creation.md b/.tools/docs/executable_creation.md
index 5194968..89516a0 100644
--- a/.tools/docs/executable_creation.md
+++ b/.tools/docs/executable_creation.md
@@ -1,6 +1,6 @@
# Create installer files
-Publishing a GitHub release builds the installers of your app for Windows (`.exe`), macOS (`.pkg`, Apple Silicon and Intel) and Linux (`.sh`) and attaches them to the release.
+Publishing a GitHub release builds the installers of your app and attaches them to the release: Windows (`.exe`), macOS (`.pkg`, Apple Silicon and Intel) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app).
## What you need
diff --git a/.tools/docs/migration_0_1_39.md b/.tools/docs/migration_0_1_39.md
new file mode 100644
index 0000000..c2d3767
--- /dev/null
+++ b/.tools/docs/migration_0_1_39.md
@@ -0,0 +1,26 @@
+# Template 0.1.39: a release builds only the systems the app lists
+
+Design note for the 0.1.39 migration (`.template_sync/migrations/v0_1_38_to_v0_1_39.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
+
+`before_getting_started.md` and `executable_creation.md` said that publishing a release builds installers for Windows, macOS and Linux. A release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml`, and every system only when that list is missing (`.tools/python/release_platforms.py`). A reader who lists fewer systems expected installers that never came.
+
+## 2. What changes
+
+Both intros now say a release builds installers for Windows, macOS and Linux, "or only the systems you list under `distribution.platforms`", and link [`distribution` in the manifest guide](app_manifest.md#distribution-how-people-get-the-app). No code changes.
+
+## 3. What the migration does
+
+* Each of the two files is replaced by the 0.1.39 page when it is still the 0.1.38 template file, compared with LF line endings (the frozen copies are in `.template_sync/resources/v0_1_38_to_v0_1_39/previous/`). The file keeps its own line endings.
+* A file the app changed is left as it is (`SKIPPED`, with a note of the sentence to add by hand).
+* A missing file is not created, and nothing is deleted. A second run changes nothing.
+
+## 4. Adopting it
+
+Take this template version (the synchronization pull request). For a skipped file, add the sentence by hand or compare it with the template's page.
+
+## 5. What is checked here
+
+* Tests (`tests/test_template_sync_0_1_39.py`): the resources are the live files and differ from the 0.1.38 ones; a 0.1.38 app reaches the live files with LF and CRLF line endings, and a second run changes nothing; a customised file is skipped with its note; a missing file is not created; the sync from 0.1.38 and the chain from older versions.
+* The older tests compare with the 0.1.38 files (`tests/_v0_1_39.py`, `before_0_1_39`).
diff --git a/tests/_v0_1_38.py b/tests/_v0_1_38.py
index 1eacb22..9f388bf 100644
--- a/tests/_v0_1_38.py
+++ b/tests/_v0_1_38.py
@@ -10,6 +10,8 @@
from pathlib import Path
from types import ModuleType
+from _v0_1_39 import before_0_1_39
+
ROOT = Path(__file__).resolve().parents[1]
MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_37_to_v0_1_38.py"
@@ -25,6 +27,7 @@ def _migration() -> ModuleType:
def before_0_1_38(relative: Path | str, data: bytes) -> bytes:
"""`data` (a live template file at `relative`) without the 0.1.38 change; any other file is returned as it is."""
+ data = before_0_1_39(relative, data)
migration = _migration()
relative = Path(relative)
if relative not in migration.FILES:
diff --git a/tests/_v0_1_39.py b/tests/_v0_1_39.py
new file mode 100644
index 0000000..3604fb2
--- /dev/null
+++ b/tests/_v0_1_39.py
@@ -0,0 +1,38 @@
+"""Helper of the tests: a live template file as it was before template 0.1.39.
+
+Template 0.1.39 replaces two guides in .tools/docs whole (FILES of the migration). The tests of the older migrations compare with
+the live files; `before_0_1_39` gives the bytes of a live file without the 0.1.39 change (the frozen 0.1.38 copy when the file is the 0.1.39
+page), so they keep checking what they checked. The 0.1.39 changes are tested in test_template_sync_0_1_39.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_38_to_v0_1_39.py"
+
+
+def _migration() -> ModuleType:
+ spec = importlib.util.spec_from_file_location("migration_0_1_39_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 before_0_1_39(relative: Path | str, data: bytes) -> bytes:
+ """`data` (a live template file at `relative`) without the 0.1.39 change; any other file is returned as it is."""
+ migration = _migration()
+ relative = Path(relative)
+ if relative not in migration.FILES:
+ return data
+ text = data.decode("utf-8")
+ newline = "\r\n" if "\r\n" in text else "\n"
+ # Only the 0.1.39 page is swapped back: older helpers may run this chain again on text that is already older.
+ if text.replace("\r\n", "\n") != (migration.RESOURCE_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n"):
+ return data
+ previous = (migration.PREVIOUS_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n")
+ return previous.replace("\n", newline).encode("utf-8")
diff --git a/tests/test_template_sync_0_1_38.py b/tests/test_template_sync_0_1_38.py
index 4aed89a..384fd64 100644
--- a/tests/test_template_sync_0_1_38.py
+++ b/tests/test_template_sync_0_1_38.py
@@ -15,6 +15,7 @@
from types import ModuleType
from _v0_1_37 import before_0_1_37
+from _v0_1_39 import before_0_1_39
ROOT = Path(__file__).resolve().parents[1]
@@ -42,7 +43,8 @@ def lf(path: Path) -> str:
def live(relative: Path) -> bytes:
- return (ROOT / relative).read_bytes()
+ """The 0.1.38 template file: the live file without the 0.1.39 change (tests/_v0_1_39.py)."""
+ return before_0_1_39(relative, (ROOT / relative).read_bytes())
def previous(relative: Path) -> bytes:
diff --git a/tests/test_template_sync_0_1_39.py b/tests/test_template_sync_0_1_39.py
new file mode 100644
index 0000000..5ee68ca
--- /dev/null
+++ b/tests/test_template_sync_0_1_39.py
@@ -0,0 +1,198 @@
+"""Tests of the 0.1.39 migration: the corrected installer intros replace the 0.1.38 guides that an app has not changed."""
+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_38 import before_0_1_38
+
+
+ROOT = Path(__file__).resolve().parents[1]
+MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_38_to_v0_1_39.py"
+SYNC_PATH = ROOT / ".template_sync/sync.py"
+DOCS = ROOT / ".tools/docs"
+PLATFORMS_LINK = "](app_manifest.md#distribution-how-people-get-the-app)"
+
+
+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_39")
+
+
+def lf(path: Path) -> str:
+ return path.read_bytes().decode("utf-8").replace("\r\n", "\n")
+
+
+def live(relative: Path) -> bytes:
+ return (ROOT / relative).read_bytes()
+
+
+def previous(relative: Path) -> bytes:
+ """The 0.1.38 template file (the frozen copy)."""
+ return (MIGRATION.PREVIOUS_ROOT / relative).read_bytes()
+
+
+def with_version(text: str, version: str) -> str:
+ """A copy of the template's .template_sync manifest whose template_version is `version` (sync.py refuses another target)."""
+ return re.sub(r"template_version: [0-9.]+", f"template_version: {version}", text)
+
+
+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\.(39|[4-9][0-9])\b")
+ self.assertIn(" - from: 0.1.38\n to: 0.1.39\n script: migrations/v0_1_38_to_v0_1_39.py\n", text)
+
+ def test_chains_from_older_versions_reach_0_1_39(self) -> None:
+ sync = load(SYNC_PATH, "sync_for_0_1_39")
+ manifest = sync.parse_manifest(ROOT / ".template_sync/manifest.yaml")
+ for start in ("0.0.0", "0.1.16", "0.1.37", "0.1.38"):
+ chain = sync.resolve_migration_chain(manifest["migrations"], start, "0.1.39")
+ self.assertEqual(chain[-1]["to"], "0.1.39", start)
+
+ def test_the_design_note_exists_and_is_not_in_the_docs_index(self) -> None:
+ self.assertIn(".tools/docs/migration_0_1_39.md", MIGRATION_PATH.read_text(encoding="utf-8"))
+ self.assertTrue((DOCS / "migration_0_1_39.md").is_file())
+ self.assertNotIn("migration_0_1_39.md", lf(DOCS / "README.md"))
+
+ def test_the_resources_are_the_live_guides_and_the_0_1_38_ones(self) -> None:
+ for relative in MIGRATION.FILES:
+ with self.subTest(file=str(relative)):
+ self.assertEqual((MIGRATION.RESOURCE_ROOT / relative).read_bytes(), live(relative))
+ self.assertNotEqual(previous(relative), live(relative))
+ resources = sorted(p.relative_to(MIGRATION.RESOURCE_ROOT) for p in MIGRATION.RESOURCE_ROOT.rglob("*") if p.is_file())
+ expected = sorted([*MIGRATION.FILES, *(Path("previous") / relative for relative in MIGRATION.FILES)])
+ self.assertEqual(resources, expected)
+
+ def test_the_older_tests_see_the_0_1_38_guides(self) -> None:
+ for relative in MIGRATION.FILES:
+ with self.subTest(file=str(relative)):
+ self.assertEqual(before_0_1_38(relative, live(relative)), before_0_1_38(relative, previous(relative)))
+
+ def test_the_intros_name_distribution_platforms_and_link_it(self) -> None:
+ for relative in MIGRATION.FILES:
+ text = lf(ROOT / relative)
+ with self.subTest(file=str(relative)):
+ self.assertIn("or only the systems you list under `distribution.platforms`", text)
+ self.assertIn(PLATFORMS_LINK, text)
+ self.assertIn("### `distribution`: how people get the app\n", lf(DOCS / "app_manifest.md"), "the anchor the intros link")
+
+
+class MigrationTests(unittest.TestCase):
+ def setUp(self) -> None:
+ self.repo = Path(tempfile.mkdtemp(prefix="lc_0_1_39_"))
+ for relative in MIGRATION.FILES:
+ self.put(relative, previous(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.FILES:
+ with self.subTest(file=str(relative)):
+ self.assertEqual((self.repo / relative).read_bytes().replace(b"\r\n", b"\n"), live(relative))
+
+ def test_an_app_of_0_1_38_gets_the_guides_and_a_second_run_changes_nothing(self) -> None:
+ log = self.run_migration()
+ self.assert_template_state()
+ 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.assertNotIn("SKIPPED", again)
+ self.assert_template_state()
+
+ def test_crlf_is_kept(self) -> None:
+ for relative in MIGRATION.FILES:
+ self.put(relative, previous(relative).replace(b"\n", b"\r\n"))
+ log = self.run_migration()
+ self.assertNotIn("SKIPPED", log)
+ self.assert_template_state()
+ for relative in MIGRATION.FILES:
+ with self.subTest(file=str(relative)):
+ self.assertNotIn(b"\n", (self.repo / relative).read_bytes().replace(b"\r\n", b""))
+
+ def test_a_customised_guide_is_skipped_with_a_note_and_the_other_changes(self) -> None:
+ relative = Path(".tools/docs/executable_creation.md")
+ own = previous(relative) + b"\n## Our own release notes\n\nOur own steps.\n"
+ page = self.put(relative, own)
+ log = self.run_migration()
+ self.assertIn(f"{relative}: SKIPPED: customised (not the 0.1.38 template file)", log)
+ self.assertIn("By hand: where the page says a release builds installers", log)
+ self.assertEqual(page.read_bytes(), own)
+ self.assertIn("done: 1 file(s) changed", log)
+
+ 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:
+ relative = Path(".tools/docs/before_getting_started.md")
+ self.put(relative, b"\xff\xfe not utf-8")
+ log = self.run_migration()
+ self.assertIn(f"{relative}: SKIPPED", log)
+ self.assertEqual((self.repo / relative).read_bytes(), b"\xff\xfe not utf-8")
+
+ def sync(self, start: str) -> subprocess.CompletedProcess[str]:
+ manifest = self.repo / ".template_sync/manifest.yaml"
+ if not manifest.exists():
+ 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.39 (later templates add migrations).
+ manifest.write_text(with_version(manifest.read_text(encoding="utf-8"), "0.1.39"), encoding="utf-8")
+ command = [sys.executable, str(self.repo / ".template_sync/sync.py"), "--from-version", start, "--to-version", "0.1.39", "--repository-root", str(self.repo)]
+ env = {key: value for key, value in os.environ.items() if key != "PYTHONPATH"}
+ return subprocess.run(command, capture_output=True, text=True, env=env, check=False)
+
+ def test_the_sync_script_runs_the_migration_from_0_1_38(self) -> None:
+ result = self.sync("0.1.38")
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertIn("[migration 0.1.39]", result.stdout)
+ self.assert_template_state()
+ again = self.sync("0.1.38")
+ self.assertIn("[migration 0.1.39] done: no repository changes were required", again.stdout)
+
+ def test_the_sync_chain_from_0_1_37_reaches_the_live_guides(self) -> None:
+ """0.1.38 replaces the 0.1.37 guides, then 0.1.39 replaces them again."""
+ for relative in MIGRATION.FILES:
+ self.put(relative, before_0_1_38(relative, previous(relative)))
+ self.assertNotEqual((self.repo / relative).read_bytes(), previous(relative))
+ result = self.sync("0.1.37")
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertNotIn("SKIPPED", result.stdout)
+ self.assert_template_state()
+
+
+if __name__ == "__main__":
+ unittest.main()