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