From cee84cba8d93bae5dd877b4eebdd12799d137005 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:19:01 +0000 Subject: [PATCH 01/12] Docs: rewrite the notebook usage and installed-app troubleshooting pages for app users Lead with the task, one section per thing to do, add where the logs are, explain the certificate workaround without implementation detail, and name the Welcome buttons as the notebook shows them. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- .tools/docs/notebook_usage.md | 35 ++++++----- .tools/docs/troubleshooting_installed_app.md | 65 ++++++++++---------- 2 files changed, 54 insertions(+), 46 deletions(-) diff --git a/.tools/docs/notebook_usage.md b/.tools/docs/notebook_usage.md index 10ff7a6..209dce7 100644 --- a/.tools/docs/notebook_usage.md +++ b/.tools/docs/notebook_usage.md @@ -1,34 +1,41 @@ # Use notebooks after installation -After you install the desktop application, this guide will show you how to use the Jupyter notebooks that come with it. +How to open an installed app, run its notebooks and update them. -## 1. Launching the Application +## Open the app To open the application, go to the Start Menu (Windows), the Applications folder (macOS) or your applications menu (Linux). Search for the application name and click its icon to start it. -## 2. Welcome Notebook +A terminal window opens first. It keeps JupyterLab running: leave it open while you work. After a few seconds, JupyterLab opens in your web browser with the Welcome notebook: -When you start the application, a terminal will pop up. +![Welcome Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Welcome_Notebook.png) -> Don't be scared by the terminal, it is normal: it keeps your Jupyter Lab session running. **Do not close the terminal** until you have finished working with your notebooks. When you have, stop the Jupyter Lab session with **File > Shut Down** in Jupyter Lab (or click on the terminal window and press `Ctrl+C`). The terminal then asks you to press `Enter`, and closes. +## Open a notebook -After some seconds, Jupyter Lab will open in your default web browser. The welcome notebook will appear automatically: +Run the cell of the Welcome notebook. It shows a table of the app's notebooks, with their version and whether a newer version exists. Click **Open the notebook** in the last column to open a notebook in a new tab. -![Welcome Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Welcome_Notebook.png) +If the app's repository on GitHub is private, the Welcome notebook asks for a GitHub personal access token to check for new versions: see [Generate a GitHub personal access token](personal_access_token.md). + +## Run a notebook + +Notebooks made with LabConstrictor can hide their code. Run each cell with its play button, or select the cell and click the play button in the top toolbar. The **Show/Hide Code** button in the toolbar shows the code. See [Hide code cells in notebooks](code_hiding.md) for pictures. If you are new to JupyterLab, see [this JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md). + +## Update a notebook -### Updating a notebook +When a newer version of a notebook is published, the Welcome notebook shows **Update** next to it. -When a newer version of a notebook is published, the Welcome notebook shows **Update** next to it. Updating replaces your copy of the notebook, so before anything changes it asks you to confirm, and it keeps your current copy, with your changes and outputs, as `.backup-.ipynb` in the same folder. Close the notebook's tab before updating: otherwise JupyterLab can save the old copy over the new one. If the download fails, your notebook is not changed. +1. Close the notebook's tab first. Otherwise JupyterLab can save the old copy over the new one. +2. Click **Update**, then confirm with **Back up and update**. -## 3. How to Run Notebooks? +Your current copy, with your changes and outputs, is kept as `.backup-.ipynb` in the same folder. If the download fails, your notebook is not changed. -You might be used to work with notebooks on JupyterLab (in case you need some guidance on JupyterLab check [this guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md)). Still, LabConstrictor uses some features that can slightly change how you interact with notebooks. Please check [this guide](code_hiding.md) to understand how to run notebooks packaged with LabConstrictor. +## Close the app -## 4. Accessing your Notebooks +Keep the terminal window open until you have finished working with your notebooks. When you have, stop the Jupyter Lab session with **File > Shut Down** in Jupyter Lab (or click on the terminal window and press `Ctrl+C`). The terminal then asks you to press `Enter`, and closes. -Once you run the welcome notebook, a dashboard will show a list of available notebooks. It looks similar to the screenshot in the [Welcome Notebook](#2-welcome-notebook) step. +## If something does not work -In the last column of the dashboard, you'll see a button called `Open the notebook`. Click it to open that notebook in a new tab and run it just like you did with the welcome notebook. +See [Troubleshooting an installed app](troubleshooting_installed_app.md). --- diff --git a/.tools/docs/troubleshooting_installed_app.md b/.tools/docs/troubleshooting_installed_app.md index c91847b..76cf272 100644 --- a/.tools/docs/troubleshooting_installed_app.md +++ b/.tools/docs/troubleshooting_installed_app.md @@ -2,67 +2,68 @@ Problems with an app on your computer, after you installed it. For problems with your repository on GitHub, see [Troubleshooting repository setup](troubleshooting.md). +## Where to find the logs + +Two files in the app's install folder (the folder you chose when you installed it) record what happened: + +- `menuinst_debug.log`: what the installer did. +- `launcher_debug.log`: what happened when you opened the app. If the app cannot start, a message names this file. + +Send them along when you ask the app's developer for help. + ## App still appears in the Windows Installed apps list after uninstalling -On Windows, it may happen that, after uninstalling the app from `Settings > Apps > Installed apps` as explained in [Uninstall an app](install.md#uninstall-an-app), the app still appears in the list and does not allow you to uninstall it again, showing a message like: +On Windows, after you uninstall the app from `Settings > Apps > Installed apps` as explained in [Uninstall an app](install.md#uninstall-an-app), the app can stay in the list and refuse to uninstall again, with a message like this: ![Uninstall error message](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/troubleshooting/Not_Uninstall.png) -The solution is to go to the Control Panel and uninstall it from there. To do this: +Uninstall it from the Control Panel instead: 1. Open the Control Panel. You can search for it in the Windows search bar. 2. Go to `Programs > Programs and Features`. -3. Find the LabConstrictor-based app in the list, right-click on it, and select `Uninstall`. -4. A message may appear saying something like: "An error occurred while trying to uninstall xxx. It might have already been uninstalled." Click `Yes` to confirm. +3. Find the app in the list, right-click it, and select `Uninstall`. +4. A message may say something like "An error occurred while trying to uninstall xxx. It might have already been uninstalled." Click `Yes`. -This should remove the app even if the previous error message appears. +The app is then removed from the list. ## Windows asks for administrator rights for python.exe while uninstalling Uninstalling an app made with template 0.1.20 or earlier may show a User Account Control prompt: "Do you want to allow this app from an unknown publisher to make changes to your device? python.exe", with the program location `"\python.exe" -m conda.core.initialize ...`. -The prompt is not needed. Click **No**. The uninstaller then shows a "Failed to clean AutoRun" error with Abort, Retry and Ignore: click **Ignore**. The uninstall finishes normally and nothing outside the app folder is changed. Clicking **Yes** does not help: the same step fails again and shows the same error, and **Retry** asks a second time. +1. Click **No**. The prompt is not needed. +2. The uninstaller then shows a "Failed to clean AutoRun" error with Abort, Retry and Ignore: click **Ignore**. + +The uninstall then finishes normally, and nothing outside the app folder is changed. **Yes** and **Retry** do not help: the same error comes back. Do not click **Abort**, even though it is the default button: it stops the uninstall halfway and leaves the app folder on disk. If that happened, run `Uninstall-.exe` in the app folder again. -The cause is a conda bug in the tool that built the installer (conda/conda#16856). Installers built with template 0.1.21 or later do not have it; see [migration_0_1_21.md](migration_0_1_21.md). +Installers built with template 0.1.21 or later do not have this problem ([details](migration_0_1_21.md)). ## The notebook fails with "No module named ..." although the installation finished -If someone once ran `python -m ipykernel install --user` on the computer (common with Anaconda or pip setups), Jupyter has a personal "python3" kernel in the user's folder (`~/.local/share/jupyter/kernels/python3` on Linux, `~/Library/Jupyter/kernels/python3` on macOS, `%APPDATA%\jupyter\kernels\python3` on Windows). Apps made with template 0.1.23 or earlier then run their notebooks in that other Python, and the first cell that imports the app fails with `ModuleNotFoundError: No module named ''`. +The first cell that imports the app fails with `ModuleNotFoundError: No module named ''`. This happens with apps made with template 0.1.23 or earlier when someone once ran `python -m ipykernel install --user` on the computer (common with Anaconda or pip setups). Jupyter then has a personal "python3" kernel, and the app's notebooks run in that other Python instead of the app's own. + +Install a release made with template 0.1.24 or later: it always uses the app's own Python. Until then, you can delete the personal kernel folder, but the other Jupyter installations on the computer that use it lose it too: -Install a release made with template 0.1.24 or later: its launcher always uses the app's own kernel. Until then, removing that personal kernel folder also works, but it affects the other Jupyter installations that use it. See [migration_0_1_24.md](migration_0_1_24.md). +- Linux: `~/.local/share/jupyter/kernels/python3` +- macOS: `~/Library/Jupyter/kernels/python3` +- Windows: `%APPDATA%\jupyter\kernels\python3` ## My changes to a notebook are gone after an update -Since template 0.1.31, the **Update** button of the Welcome notebook keeps your copy before it replaces a notebook: look for `.backup-.ipynb` in the same folder, and open it in JupyterLab. Apps made with template 0.1.30 or earlier replace the notebook without a copy. +The **Update** button of the Welcome notebook keeps your copy before it replaces a notebook: look for `.backup-.ipynb` in the same folder and open it in JupyterLab. Apps made with template 0.1.30 or earlier replace the notebook without keeping a copy. ## JupyterLab does not start because Windows reports an ASN.1 certificate error -LabConstrictor-based installers include a TLS-resilient launcher. It attempts -native operating-system certificate verification before JupyterLab imports -Tornado and provides a verified CA-bundle fallback when a malformed Windows -certificate-store entry cannot be parsed. SSL and hostname verification are -never disabled. +A broken certificate in the Windows certificate store can stop JupyterLab from starting. The app's launcher works around it: it first uses the system's certificates and, if one of them cannot be read, falls back to a verified certificate bundle. Certificate checks are never switched off. `launcher_debug.log` says which one was used. -The constructor environment intentionally does not include -`pip-system-certs`. Its automatic Python startup hook can fail before the -application launcher has an opportunity to select the verified fallback. -Post-install pip commands instead use an explicit CA bundle while preserving -certificate verification. +If your organisation uses its own certificate authority, save its certificates as a PEM file and set one of these environment variables to the path of that file before you install or open the app: -Diagnostic information is written to `launcher_debug.log` and -`menuinst_debug.log` in the installation directory. Maintainers can run the -same preflight used by the installer with: +- `LABCONSTRICTOR_CA_BUNDLE`, for every LabConstrictor app; +- `_CA_BUNDLE`, for one app: the app's name in capitals, with spaces and punctuation replaced by `_` (for the app "My Project", `MY_PROJECT_CA_BUNDLE`). + +To test the launcher without opening JupyterLab, run this in a command prompt (replace `` and ``): ```text -\python.exe \PROJECT_NAME\launch_jupyter.py --self-test +\python.exe \\launch_jupyter.py --self-test ``` - -The self-test reports the project-specific CA override variable. It is derived -from the application name by replacing punctuation and spaces with underscores -and converting it to uppercase, for example `MY_PROJECT_CA_BUNDLE`. All -LabConstrictor-based applications also accept the shared -`LABCONSTRICTOR_CA_BUNDLE` variable. Set either variable to an organization PEM -bundle before installation or launch when a private certificate authority is -required. From 36fbf7d0aa633e67020c08ecdea2c7d0db991137 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:21:30 +0000 Subject: [PATCH 02/12] Docs: initialise_repository walks through the form, with what you need and checks Names the token the form accepts (classic, ghp_), the form's buttons and fields, the pull request it opens, how to check the result and what to do when the form fails. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- .tools/docs/initialise_repository.md | 45 ++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/.tools/docs/initialise_repository.md b/.tools/docs/initialise_repository.md index 0b31be3..ca5d5c2 100644 --- a/.tools/docs/initialise_repository.md +++ b/.tools/docs/initialise_repository.md @@ -1,13 +1,46 @@ # Initialise your repository -Now that your repository is set up, you can start to customise it. To get started, you will need: +The repository initialiser, a web form, fills your repository with your app's name, version, description and images. It opens a pull request in your repository; you merge it to finish. -- A name for your project/application (e.g., `CellAnalyzer`). -- An initial version number (e.g., `0.0.1`). -- A one-sentence summary of what your app does, its kind, and the software it also works in. They go into the description file for the [App Centre](app_manifest.md). -- (Optionally) Images for App installer customisation. See [Installer Images Customisation](installer_images.md) for more details on the images you can provide. +## What you need -Once you have everything ready, go to [https://labconstrictor-form.streamlit.app/](https://labconstrictor-form.streamlit.app/). If you see a `Zzzz` message for inactivity, click `Yes, get this app back up!`. Next, select `Start initialisation` in the **Initialise GitHub repository** section. Follow the instructions on the website. After you submit the form, a Pull Request with suggested changes will be created in your repository. To learn how to accept these suggestions, see [How to accept a Pull Request](accept_pull_request.md). After you accept the suggestions, the main README will move to [.tools/docs](.). But don't be afraid, the new README will have a link pointing the instructions for future reference, so you won’t lose access to them. +- A repository created from the template: see [Create your repository](create_repository.md). +- A name for your app (for example `CellAnalyzer`). We recommend the name of your GitHub repository. It may contain letters, numbers, spaces, `_`, `-` and `.`, from 3 to 50 characters. +- A first version number in the form `MAJOR.MINOR.PATCH` (for example `0.0.1`). +- A GitHub personal access token (classic, it starts with `ghp_`) that can write to the repository: see [Generate a GitHub personal access token](personal_access_token.md). The form refuses a fine-grained token (`github_pat_...`). +- Recommended: a one-sentence summary of what your app does, its kind, and the software it also works in. They go into the description file for the App Centre ([Describe your app for the App Centre](app_manifest.md)). +- Optional: PNG images for the installer. See [Customise the installer images](installer_images.md). + +## Fill in the form + +1. Open the [repository initialiser](https://labconstrictor-form.streamlit.app/). If it shows a `Zzzz` message, click `Yes, get this app back up!` and wait. +2. In the **Initialise GitHub repository** section, click **Start initialisation**. +3. Fill in **Project name** and **Initial project version**. Tick **Disable automatic code hiding in notebooks** only if users must edit your notebooks' code (see [Hide code cells in notebooks](code_hiding.md)). +4. Under **Describe your app (recommended)**, write the summary, choose the kind of app and the software it also works in. +5. Optionally upload the icon, welcome and header images. +6. Click **Validate submission**. If something is missing, the form lists what to fix. +7. Under **⬆️ Upload it to GitHub**, enter your repository's address (for example `https://github.com/your-lab/CellAnalyzer`) and your token, then click **🚀 Create pull request**. + +## Accept the pull request + +The form opens a pull request titled "Pull request for initialisation". Merge it: see [Accept a pull request](accept_pull_request.md). + +## Check that it worked + +After you merge the pull request: + +- Your repository's main page shows a new README titled with your app's name. +- These guides are listed in `.tools/docs/README.md`: the main README of the template moved there, and the new README links to it. +- `construct.yaml` shows your app's name and version instead of `PROJECT_NAME` and `VERSION_NUMBER`. + +## If something does not work + +- **The form says the token is fine-grained or not valid.** Create a classic token that starts with `ghp_` ([how](personal_access_token.md)). +- **The form says the repository address is not valid.** Use the form `https://github.com//`. +- **"Failed to push changes" or "Failed to create pull request".** Check that the token has the **repo** scope and belongs to an account that can write to the repository, and that the repository's default branch is `main`. +- **No pull request appears.** Look at the messages at the bottom of the form: they say which step failed. You can submit the form again. + +For other problems with your repository, see [Troubleshooting repository setup](troubleshooting.md). --- From d613106700bd5babe4e5289f4d958ed61c2789e6 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:21:30 +0000 Subject: [PATCH 03/12] Docs: requirements and upload pages get what you need, checks and fixes The form accepts only package==version; all notebooks share one python_version; the generator saves _requirements.yaml. Updating a notebook no longer asks to run a 'bottom cell'. The upload page says what the workflow does and how to check it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- .tools/docs/notebook_requirements.md | 87 ++++++++++++++-------------- .tools/docs/notebook_upload.md | 61 +++++++++++-------- 2 files changed, 83 insertions(+), 65 deletions(-) diff --git a/.tools/docs/notebook_requirements.md b/.tools/docs/notebook_requirements.md index ac4a480..c686776 100644 --- a/.tools/docs/notebook_requirements.md +++ b/.tools/docs/notebook_requirements.md @@ -1,47 +1,42 @@ # Generate the requirements of your notebook -You can get your Jupyter notebook’s requirements automatically with Option 1 or manually with Option 2. +Every notebook you upload needs a `requirements.yaml` file: the Python version and the packages it uses, each with its exact version. The installer installs these packages on your users' computers. -* **Option 1 (Automated):** Recommended if you need to generate requirements from scratch. -* **Option 2 (Manual):** Recommended if you already have a versioned `requirements.txt` file, as it will be faster. +There are two ways to make the file: ---- +* **Option 1 (automated):** the Requirements Generator notebook reads the packages from the Python environment where your notebook runs. Use it when you start from scratch. +* **Option 2 (manual):** you write the file yourself and check it with the Requirements Validator notebook. Faster if you already have a `requirements.txt` with versions. -## Option 1: Automated Extraction of Requirements +## What you need -### 1. Open the Requirements Generator Notebook +- Your notebook, running without errors in a Python environment: on your computer (conda or virtualenv) or in Google Colab. +- For Option 1 on your computer: that same environment, with Jupyter. The generator must run in the environment your notebook uses, because it reads the package versions from it. -**⚠️ IMPORTANT:** You will need to choose the option based on the environment you used to run the target notebook whose requirements you want to extract. +## Option 1: Automated extraction of requirements - * Did you ran your notebook locally on your machine (with Conda/VirtualEnv)? ➡️ Locally - * Did you ran your notebook on Google Colab? ➡️ Online +### 1. Open the Requirements Generator notebook -In both cases the Python environment that you use for the notebook, needs to run without errors. Knowing this please choose the option that best suits your case: +Open it where your notebook runs: -* **Locally:** Go to the [Requirements_Generator.ipynb](../notebooks/Requirements_Generator.ipynb) notebook, download it (clicking on the button indicated on the screenshot below ⬇️) and open it in your local Python environment (conda or virtualenv). - > **Note**: When using it locally, the Python environment where you open the requirements generator notebook needs to be exactly the one you use to run the target notebook whose requirements you want to extract. For example, if you have multiple conda environments, you need to make sure that you use the same conda environment that you use to run the target notebook. - -![Download Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Download_Notebook.png) - -* **Google Colab:** Open the notebook directly in Google Colab by opening the [Requirements Generator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Generator.ipynb). +* **On your computer:** download [Requirements_Generator.ipynb](../notebooks/Requirements_Generator.ipynb) (with the download button shown below) and open it in the environment you use for your notebook. If you have several conda environments, use the one your notebook runs in. -### 2. Run the Requirements Generator + ![Download Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Download_Notebook.png) -Follow the instructions provided inside the notebook to generate the `requirements.yaml` file. You will be prompted to provide the path to the notebook file you wish to analyse. +* **Google Colab:** open the [Requirements Generator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Generator.ipynb). Colab runs each notebook in its own session, so the packages your notebook installs must be installed in the generator's session too: the generator finds your notebook's `pip install` commands and offers a cell that runs them. ---- +### 2. Run the Requirements Generator -## Option 2: Manual Extraction of Requirements +Run its cells in order and follow the instructions in the notebook: choose your notebook, add helper files your notebook uses if any, then generate the file. It saves `_requirements.yaml` next to the generator (in Colab it is also downloaded). You can upload it with that name: the upload form saves it as `requirements.yaml`. -### 1. Create a `requirements.yaml` File +## Option 2: Manual extraction of requirements -You will need to create a `requirements.yaml` file similar to the [example requirements.yaml file](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/templates/requirements.yaml). This file must contain the following three fields: +### 1. Create a `requirements.yaml` file -* **`dependencies`:** A list of all packages used in the notebook along with their versions. The list needs to be indexed with a hyphen (`-`) followed by a space before each package. -* **`python_version`:** The version of Python used in the notebook (e.g., `3.11.1`). -* **`description`:** A short description of the notebook and its purpose. +Start from the [example requirements.yaml file](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/templates/requirements.yaml). It has three fields: -**Example File Content:** +* **`dependencies`:** every package the notebook uses, one per line, each starting with `- ` and fixed to one version with `==` (`pandas==2.2.2`). Optional extras are allowed (`colabfold[alphafold,openmm]==1.6.3`). The upload form refuses ranges such as `pandas>=2`. +* **`python_version`:** the Python version the notebook runs with (for example `3.11.1`). All notebooks of an app must use the same one. +* **`description`:** one sentence on what the notebook does. ```yaml dependencies: @@ -50,28 +45,40 @@ dependencies: - tqdm==4.67.1 description: This notebook is for analyzing cell migration data... python_version: 3.11.1 - ``` -### 2. Open the Requirements Validator Notebook +### 2. Check it with the Requirements Validator notebook -We recommend using **Google Colab** for this step, as you do not need a specific Python environment to run the validator. +* **Google Colab (recommended, nothing to install):** open the [Requirements Validator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Validator.ipynb). +* **On your computer:** download [Requirements_Validator.ipynb](https://raw.githubusercontent.com/CellMigrationLab/LabConstrictor/main/.tools/notebooks/Requirements_Validator.ipynb) and open it in any Python environment that has `ipywidgets`. -* **Google Colab (Recommended):** Open the notebook directly by opening the [Requirements Validator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Validator.ipynb). -* **Locally:** Download the [Requirements_Validator.ipynb](https://raw.githubusercontent.com/CellMigrationLab/LabConstrictor/main/.tools/notebooks/Requirements_Validator.ipynb) and open it in any Python environment that has `ipywidgets` installed. +Follow the instructions in the notebook and give it your `requirements.yaml` when it asks. -### 3. Run the Requirements Validator +## Check that it worked -Follow the instructions provided inside the notebook to validate your file. You will need to provide the path to your newly created `requirements.yaml` file when prompted. +- You have a `requirements.yaml` (or `_requirements.yaml`) file. +- Every line under `dependencies` has the form `package==version`, and `python_version` is the version your notebook runs with. ---- +You are ready to [upload your notebook](notebook_upload.md). + +## If something does not work + +- **A package is missing from the generated file.** The generator finds only packages installed in the environment it runs in. Open it in the environment of your notebook, or add the package by hand with its version. +- **The upload form says "Dependency '...' is not in the correct format".** Fix that line to `package==version`. +- **The workflow stops after the upload with conflicting versions.** Two notebooks ask for different versions of a package: see [When notebooks ask for different versions of a package](#when-notebooks-ask-for-different-versions-of-a-package). -## What happens next: the lock file +## What happens after you upload: the lock file -When you push a notebook with its `requirements.yaml`, the workflow **Updates on notebook change** merges the requirements of every notebook into `requirements.txt` (plus `requirements_gpu.txt` and, if a notebook needs them, `requirements-windows.txt`, `requirements-linux.txt` or `requirements-macos.txt`). +When a notebook and its `requirements.yaml` reach the repository, the workflow **Updates on notebook change** merges the requirements of every notebook into `requirements.txt`, plus `requirements_gpu.txt` and, if a notebook needs them, `requirements-windows.txt`, `requirements-linux.txt` or `requirements-macos.txt`. The installer uses `requirements_gpu.txt` when it finds an NVIDIA GPU on Windows or Linux. In that file `tensorflow` becomes `tensorflow[and-cuda]` on Linux only: TensorFlow has had no Windows GPU build since version 2.10, and its CUDA packages exist only for Linux, so Windows keeps plain `tensorflow` (CPU). +The workflow then writes a **lock file** next to each requirements file (`requirements.lock.txt`, ...). A lock file lists every package the installer installs, including the packages your packages depend on, each with its exact version, for Windows, macOS and Linux. The installer installs the lock file, so every installation of a release gets the same versions. + +* A lock file changes only when its requirements file, the Python version or the JupyterLab version changes. Pushing a notebook without new requirements does not move any version. +* To move every package to its newest version, delete the `requirements*.lock.txt` files and run the workflow by hand (**Actions > Updates on notebook change > Run workflow**). +* If the requirements cannot be locked, the workflow shows a warning and the installer installs the plain `requirements.txt` instead. + ### When notebooks ask for different versions of a package The merge never changes a notebook's requirement silently. Requirements are kept as written (`numpy>=1.24` stays `numpy>=1.24`), and the requirements of several notebooks are combined (`numpy>=1.24,<2`). The workflow stops, and no requirements file is written, when: @@ -92,13 +99,9 @@ overrides: reason: "Notebook A was re-run with numpy 2.0.0 and gives the same results; notebook B needs 2.0." ``` -The decision and its reason are written at the top of the generated requirements files. Pushing `requirements_overrides.yaml` runs the workflow again. A release also stops while a conflict is not resolved. Requirements with different platform markers (`; sys_platform == "win32"`) are kept as separate lines, and `NumPy`, `numpy` and `num_py` count as the same package, as for pip. +The decision and its reason are written at the top of the generated requirements files. Pushing `requirements_overrides.yaml` runs the workflow again. A release also stops while a conflict is not resolved. -It then writes a **lock file** next to each of them (`requirements.lock.txt`, ...). A lock file lists every package the installer installs, including the packages your packages depend on, each with its exact version, for Windows, macOS and Linux. The installer installs the lock file, so every installation of a release gets the same versions. - -* A lock file changes only when its requirements file, the Python version or the JupyterLab version changes. Pushing a notebook without new requirements does not move any version. -* To move every package to its newest version, delete the `requirements*.lock.txt` files and run **Updates on notebook change** by hand (**Actions > Updates on notebook change > Run workflow**). -* If the requirements cannot be locked, the workflow shows a warning and the installer installs the plain `requirements.txt` instead. +Requirements with different platform markers (`; sys_platform == "win32"`) are kept as separate lines, and `NumPy`, `numpy` and `num_py` count as the same package, as for pip. --- diff --git a/.tools/docs/notebook_upload.md b/.tools/docs/notebook_upload.md index 3e00273..e0fc1c7 100644 --- a/.tools/docs/notebook_upload.md +++ b/.tools/docs/notebook_upload.md @@ -1,16 +1,21 @@ # Add or update a notebook -If you want to add or update a notebook in your project repository, just follow these steps to upload it smoothly. +Upload a notebook and its `requirements.yaml` to your repository with the LabConstrictor web form. The form opens a pull request; when you merge it, GitHub checks that the notebook's packages can be installed together. + +## What you need + +- An initialised repository: see [Initialise your repository](initialise_repository.md). +- Your notebook (`.ipynb`) and its requirements file: see [Generate the requirements of your notebook](notebook_requirements.md). +- A GitHub personal access token (classic, it starts with `ghp_`): see [Generate a GitHub personal access token](personal_access_token.md). ## 1. Prepare your notebook -To ensure your notebook works with the versioning tracking provided by the LabConstrictor application, please follow these three steps to prepare your notebook: +The first cell of every notebook checks its version, so users see when a newer version exists. -1. First, create a cell at the top of your notebook (see our [JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md) if you need help with that). -2. Then, copy and paste the code below into that cell. -3. Finally, update the `current_version` variable with the version of your notebook (for example, "0.0.2") and the `notebook_name` variable with the name of your notebook file (without the .ipynb extension). +1. Add a code cell at the top of your notebook (see this [JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md) if you need help), and paste the code below into it. +2. Set `current_version` to the version of your notebook (for example `"0.0.2"`) and `notebook_name` to the name of the notebook file without `.ipynb`. -> IMPORTANT NOTE: Each time you change the notebook's logic, update the version number on `current_version` variable so users can see there is a new version. +> Each time you change what the notebook does, increase `current_version` so users can see there is a new version. ```python # @markdown Run this cell to check this notebook's version. @@ -133,38 +138,48 @@ except ImportError: display(widgets.HTML('To check the notebook version, please go to the Welcome notebook.')) ``` + ## 2. Generate the requirements file -Follow the steps in the [Obtain requirements of the notebook](notebook_requirements.md) guide to create the `requirements.yaml` file for your notebook. +Create the `requirements.yaml` file of your notebook: see [Generate the requirements of your notebook](notebook_requirements.md). ## 3. Upload to the repository -1. Open the [LabConstrictor website](https://labconstrictor-form.streamlit.app/). If you see a `Zzzz` message for inactivity, click `Yes, get this app back up!`. -2. Select **Upload/Update notebook**. -3. Upload your notebook file (`.ipynb`) and the `requirements.yaml` file you created. -4. Click **➕ Validate & Add Submission**. If the notebook and its requirements pass the checks, the notebook appears in the **📃 Submission list**. You can repeat steps 3 and 4 to add more notebooks to the list before uploading. -5. In the **⬆️ Upload it to GitHub** section, enter your repository URL and your personal access token. - * *(Don't have a token? See [How to create a personal access token](personal_access_token.md))* +1. Open the [LabConstrictor form](https://labconstrictor-form.streamlit.app/). If it shows a `Zzzz` message, click `Yes, get this app back up!` and wait. +2. Click **Upload/Update notebook**. +3. Upload your notebook file (`.ipynb`) and its requirements file. +4. Click **➕ Validate & Add Submission**. If the notebook and its requirements pass the checks, the notebook appears in the **📃 Submission list**. Repeat steps 3 and 4 to add more notebooks to the same pull request. +5. Under **⬆️ Upload it to GitHub**, enter your repository's address and your personal access token. 6. Click **🚀 Create pull request**. +## 4. Merge the pull request + +The form opens a pull request titled "Upload/Update notebook" followed by the notebook's name. Merge it: see [Accept a pull request](accept_pull_request.md). The merge starts the workflow **Updates on notebook change**, which merges the requirements of all notebooks, hides the code cells (unless you disabled it) and checks that the packages can be installed. + +## Check that it worked + +- In the **Actions** tab, the run of **Updates on notebook change** has a green tick ([how to read a run](workflow_status.md)). +- Your notebook is in `notebooks//`, next to its `requirements.yaml`. +- `notebooks/notebook_latest_versions.yaml` lists the notebook with its `current_version`. + +You can now [create the installers](executable_creation.md). -## 4. Merge and Verify +## If something does not work -If you need help merging the pull request, see the [Accept a Pull Request](accept_pull_request.md) guide for instructions. An automatic workflow will check your notebook and its dependencies. -* **Check Status:** See [How to check workflow status](workflow_status.md). -* Failure Protocol: If the merged requirements cannot be installed, the system automatically undoes the merge. Check the logs, fix the problem in your local notebook or requirements, and upload again. -* If notebooks ask for different versions of the same package, the workflow stops before anything is installed and the requirements files are not changed. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package). +- **The form refuses the requirements file.** The message names the line to fix. Each dependency must be `package==version`: see [Generate the requirements of your notebook](notebook_requirements.md). +- **The workflow failed and your merge was undone.** When the merged requirements cannot be installed, the workflow reverts your merge automatically. Open the failed run, find the package that failed in the log, fix the notebook's requirements and upload again. +- **The workflow stops with conflicting versions.** Notebooks ask for different versions of the same package; nothing is installed and the requirements files are not changed. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package). +- **The version check says "This notebook is not listed in the version file".** `notebook_name` in the first cell does not match the notebook's file name. --- ## How to update an existing notebook -Updating a notebook works the same way as adding a new one: +Updating a notebook works the same way as adding one: -1. Bump the version: In the top cell of your notebook, increase the `current_version` (for example, from '1.0.0' to '1.0.1'). -2. Regenerate requirements: Run the bottom cell to make sure `requirements.yaml` matches the new version number. -3. Upload: Use the [LabConstrictor App](https://labconstrictor-form.streamlit.app/) to upload your file. - * *Ensure the filename matches the existing one in the repository exactly.* +1. In the first cell of your notebook, increase `current_version` (for example from `1.0.0` to `1.0.1`). +2. If the notebook now uses other packages or versions, generate its requirements file again. +3. Upload the notebook and its requirements file with the [LabConstrictor form](https://labconstrictor-form.streamlit.app/), as above. Keep the notebook's file name exactly the same: a notebook with the same name replaces the old one. --- From 91b21ef9c981b44e2ab1f599d99dc98eac55400a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:21:30 +0000 Subject: [PATCH 04/12] Docs: executable_creation says what you need, how to check the release and what to do on failure Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- .tools/docs/executable_creation.md | 34 +++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/.tools/docs/executable_creation.md b/.tools/docs/executable_creation.md index 008b322..b90ce74 100644 --- a/.tools/docs/executable_creation.md +++ b/.tools/docs/executable_creation.md @@ -1,26 +1,40 @@ # Create installer files -After uploading your notebooks to the repository, follow these steps to create executable files for sharing. +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`). ## Please check before proceeding -Open the Actions tab in your repository and check that no workflows are running. If one is in progress, wait until it finishes. Starting a release while other jobs are running may cause build conflicts. +Open the **Actions** tab of your repository and check that no workflow is running. If one is in progress, wait until it finishes: a release started while another workflow runs may build from files that are about to change. ## 1. Draft a new release 1. Go to your repository's main page. -2. Click on Releases (usually on the right sidebar). -3. Click `Create a new release` and provide the following information: - - **Tag**: Click `Create a new tag` and enter a version number, for example, `0.0.1`. - > **IMPORTANT**: Make sure that it follows a semantic versioning format (MAJOR.MINOR.PATCH) e.g. `1.0.0`, `1.2.3`, `2.1.0`. A `v` in front (`v1.0.0`) also works: the installers are named with the version without it. - - **Release title**: Enter a title for your release, such as `Initial release`. - - **Description** (optional): Enter a description for your release, for example, `This is the initial release of my project.` +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 -Once you have entered all the required information, click `Publish release`. This action will start the automated workflow to create installer executable files for your notebooks. To monitor the process, see [How to check the automatic workflow status](workflow_status.md). +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 -When the automated workflow completes, open your repository's **Releases** page, open the release you published and download the installers from its **Assets** list. +- **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 From 151d8c9300b37a4c78534415cad7d93358cd7a47 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:22:23 +0000 Subject: [PATCH 05/12] Docs: tighten before_getting_started, create_repository and accept_pull_request Plain, shorter text; numbered steps; each page points to the next step. accept_pull_request says which LabConstrictor steps send pull requests. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- .tools/docs/accept_pull_request.md | 24 ++++++----------- .tools/docs/before_getting_started.md | 26 +++++++++--------- .tools/docs/create_repository.md | 38 +++++++++------------------ 3 files changed, 34 insertions(+), 54 deletions(-) diff --git a/.tools/docs/accept_pull_request.md b/.tools/docs/accept_pull_request.md index c0fd3dd..f0474f3 100644 --- a/.tools/docs/accept_pull_request.md +++ b/.tools/docs/accept_pull_request.md @@ -1,27 +1,19 @@ # Accept a pull request -Follow these steps or watch the GIF at the end to learn how to accept a Pull Request (PR) on GitHub. LabConstrictor template updates are delivered this way after you complete the [automatic synchronization setup](template_synchronization.md). +The repository initialiser, the notebook upload form and template updates all send their changes to your repository as a pull request. You accept a pull request by merging it. -## 1. Go to the Pull Requests tab +1. Open the **Pull requests** tab of your repository. -Go to the **Pull Requests** tab in your GitHub repository to see a list of all Pull Requests. You can refer to the screenshot below. + ![Pull Request Tab](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/PR_tab.png) -![Pull Request Tab](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/PR_tab.png) - -## 2. Select the Pull Request to review - -The most recent Pull Request is usually at the top. Click its title to open and review it. - -## 3. Merge the Pull Request - -Click the green **Merge pull request** button, then click **Confirm merge** to complete the process. - -## 4. Delete the branch (optional) - -Once you have merged, you can delete the related branch by clicking the **Delete branch** button. +2. Click the title of the pull request to open it. The newest one is at the top. The **Files changed** tab shows what it changes. +3. Click the green **Merge pull request** button, then **Confirm merge**. +4. Optional: click **Delete branch** to remove the branch the pull request came from. ![Accept a Pull Request GIF](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Accept_PR.gif) +The merge can start a workflow in the **Actions** tab: see [Check the status of GitHub workflows](workflow_status.md). Template updates arrive this way once you have enabled [automatic template updates](template_synchronization.md). + --- diff --git a/.tools/docs/before_getting_started.md b/.tools/docs/before_getting_started.md index 033d911..fd974a6 100644 --- a/.tools/docs/before_getting_started.md +++ b/.tools/docs/before_getting_started.md @@ -1,43 +1,43 @@ # Before getting started with LabConstrictor -Welcome to LabConstrictor! This guide will walk you through the basics and show you what you need to get started. +What LabConstrictor does, and what you need before you create your repository. ## LabConstrictor in a nutshell -LabConstrictor is a template repository that lets you turn Jupyter notebooks into desktop apps. It handles the setup for you via automated GitHub Actions. Here are its main features: +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 -LabConstrictor has a web form that makes it easy to set up your repository, add your branding, and upload or update your notebooks and their dependencies. +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 -Automatic workflows create installers for Windows (.exe), macOS (.pkg), and Linux (.sh). This makes it simple for users on any platform to install and run your notebooks. The installers are created using [Conda Constructor](https://github.com/conda/constructor). +Publishing a release builds installers for Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`) with [conda constructor](https://github.com/conda/constructor). ### Environment management -LabConstrictor uses `requirements.yaml` files to manage dependencies. Automatic workflows ensure your notebooks run consistently across different systems. LabConstrictor also includes helper notebooks for generating and validating requirement files. +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 -LabConstrictor includes helper cells that track notebook versions and notify users when updates are available. This way, everyone can use the latest features and fixes. +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 installers take care of the setup, so users can open your notebooks with a desktop app. The app shows a Welcome Dashboard where users can check versions and pick notebooks. Notebooks have hidden code and a play button to run cells, giving a clean, app-like feel. Your repository can be private or public, giving you full control over who can access and use your notebooks. +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 -If your notebooks don’t need internet access, users can run the desktop apps offline after they install them. +Once installed, the app runs without internet access, unless your notebooks need it. ## LabConstrictor requirements -To get started with LabConstrictor, you only need the following: +- **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. +- **Optional: images** (logo, banner, header) to brand the installer: see [Customise the installer images](installer_images.md). -- **🐙 GitHub Account:** You’ll need a GitHub account to make a new repository from the LabConstrictor template. -- **📒 Jupyter Notebooks:** Have your Jupyter notebooks ready to package into desktop apps. -- **🐍 Python Environment:** You’ll need a Python environment (local or online) where your notebooks run without errors. This is needed to create and check requirement files. Alternatively, you can create the requirement files yourself, but this may be prone to errors. -- **(Optional) 🖼️ Images, logo and icons:** for branding your executable installer. We recommend following the [images guidelines](./installer_images.md) for further information and guidance. +Next: [Create your repository](create_repository.md). --- diff --git a/.tools/docs/create_repository.md b/.tools/docs/create_repository.md index 0d30864..e2db347 100644 --- a/.tools/docs/create_repository.md +++ b/.tools/docs/create_repository.md @@ -1,37 +1,25 @@ # Create your repository -To start, open the [LabConstrictor template on GitHub](https://github.com/CellMigrationLab/LabConstrictor) and click the `Use this template` button at the top of the page. This will let you create a new repository using the LabConstrictor template. +Your app lives in its own GitHub repository, made from the LabConstrictor template. +1. Open the [LabConstrictor template on GitHub](https://github.com/CellMigrationLab/LabConstrictor). +2. Click the green **Use this template** button at the top right, then **Create a new repository**. -1. Click the green **Use this template** button at the top right of the main repository page. -2. Select **Create a new repository**. + ![Use template screenshot](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Use_Template.png) -![Use template screenshot](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Use_Template.png) +3. Fill in the details: + - **Include all branches:** leave it off. + - **Owner:** your personal account or your research group's organization. + - **Repository name:** a short name, for example `MyLabTools`. We recommend using it as your app's name when you initialise the repository. + - **Description** (optional): what your notebooks do, for example "Automated cell migration analysis". + - **Visibility:** **Public** to share your installers right away; **Private** to keep the code within your lab while you work on it. A private repository cannot be listed in the App Centre: make it public before you submit your app. +4. Click **Create repository**. -3. Next, you’ll need to fill in some details: - -* **Include all branches:** -Please, let the default `Off` option. - -* **Owner:** -Pick either your personal account or your research group’s organization. - -* **Repository Name:** -Pick a short, memorable name (for example, `MyLabTools`). -> **Note:** This name will be used as the default name for your application installer. - -* **Description** *(Optional)*: -Write a brief description of what your notebooks do (for example, "Automated cell migration analysis"). - -* **Visibility:** - * **Public:** Select this if you want to share your installer right away. - * **Private:** Select this if you’re still working on the tools or want to keep the code within your lab. A private repository cannot be listed in the App Centre: make it public before you submit your app. - -4. Click **Create repository**. 🎉 That’s it! Your repository is now set up and ready to go. +Next: [Initialise your repository](initialise_repository.md). ## Template updates (optional, later) -We recommend setting up automatic template updates after your first release. Without the update token, the weekly **Sync with Template Repository** run stops with the error "Synchronization setup required" as soon as a newer template version exists, and your repository receives no update pull request. See [Keep your app up to date](keep_app_up_to_date.md). +The template keeps improving, and your repository can receive the changes as pull requests. Set this up after your first release: see [Keep your app up to date](keep_app_up_to_date.md). Until you do, the weekly **Sync with Template Repository** run stops with the error "Synchronization setup required" whenever a newer template version exists. --- From 149447b6fad90dc2283ae3ef46f1029e3004b648 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:23:11 +0000 Subject: [PATCH 06/12] Docs: troubleshooting.md names the error each sync entry answers, drops design-note links The PyPI section is left as it is (a migration resource must stay byte for byte equal). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- .tools/docs/troubleshooting.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.tools/docs/troubleshooting.md b/.tools/docs/troubleshooting.md index 1c66d13..1fbcfa0 100644 --- a/.tools/docs/troubleshooting.md +++ b/.tools/docs/troubleshooting.md @@ -4,9 +4,9 @@ Problems with your repository on GitHub. For problems with an installed app on y ## Synchronisation is failing on GitHub Actions -The **Sync with Template Repository** workflow needs the encrypted repository secret `LABCONSTRICTOR_SYNC_TOKEN` because template migrations can update files in `.github/workflows/`. Follow the [automatic template synchronization guide](template_synchronization.md) for the complete beginner-friendly setup. +The **Sync with Template Repository** workflow needs the repository secret `LABCONSTRICTOR_SYNC_TOKEN`, because template updates can change files in `.github/workflows/`. The setup is in [Enable automatic LabConstrictor template updates](template_synchronization.md). -### The synchronization token is missing +### "Synchronization setup required": the token is missing Create the token and save it under **Settings → Secrets and variables → Actions** with this exact name: @@ -16,33 +16,33 @@ LABCONSTRICTOR_SYNC_TOKEN ### GitHub refuses to update a workflow file -If the error says GitHub is refusing to create or update a workflow without `workflows` permission, ensure the token has all of these repository permissions: +If the error says GitHub refuses to create or update a workflow without `workflows` permission, check that the token has all of these repository permissions: - **Contents:** Read and write - **Pull requests:** Read and write - **Workflows:** Read and write -Repositories created before template version `0.1.12` also need the one-time workflow edit described in the synchronization guide so the existing workflow starts using the secret. +Repositories created before template version `0.1.12` also need the one-time workflow edit described in the synchronization guide, so that the workflow uses the secret. ### Bad credentials or authentication failed -The token may have expired or been revoked. Create a replacement token and update the existing `LABCONSTRICTOR_SYNC_TOKEN` secret. +The token has expired or was revoked. Create a new token and update the `LABCONSTRICTOR_SYNC_TOKEN` secret: see [Renewing an expired token](template_synchronization.md#renewing-an-expired-token). ## The release stops at "check_placeholders.py" -The release workflow checks, before it builds the installers, that no template placeholder (`PROJECT_NAME`, `PYTHON_PROJ_NAME`, `UNDERSCORED_PROJECT_NAME`, ...) is left in a file the installer ships. An installer built with one would fail on the users' computers (for example `No module named 'PYTHON_PROJ_NAME'` at the end of the installation). +Before it builds the installers, the release workflow checks that no template placeholder (`PROJECT_NAME`, `PYTHON_PROJ_NAME`, `UNDERSCORED_PROJECT_NAME`, ...) is left in a file the installer ships. An installer with one would fail on your users' computers (for example `No module named 'PYTHON_PROJ_NAME'` at the end of the installation). -The log of the failed step lists each file and line. Replace the placeholder there with your app's value: `PYTHON_PROJ_NAME` is the Python package of the app (usually its folder in `src/`), `PROJECT_NAME` the app name. For `app/menuinst/Welcome.ipynb`, edit `.tools/templates/Welcome_template.ipynb` instead: the Welcome notebook is made from it at every release. Commit, then publish the release again. See [migration_0_1_23.md](migration_0_1_23.md). +The log of the failed step lists each file and line. Replace the placeholder there with your app's value: `PYTHON_PROJ_NAME` is the Python package of the app (usually its folder in `src/`), `PROJECT_NAME` the app name. For `app/menuinst/Welcome.ipynb`, edit `.tools/templates/Welcome_template.ipynb` instead: the Welcome notebook is made from it at every release. Commit, then publish the release again. ## The release stops at "Installers to build" -The `platforms` job of the release workflow reads `distribution.platforms` in `labconstrictor-app.yaml` to decide which installers to build. It stops when the file is not valid YAML, when `platforms` is not a list, or when it lists none of the systems the release builds installers for: `windows-x86_64`, `linux-x86_64`, `macos-arm64` and `macos-x86_64`. The log of the step says which. Fix `labconstrictor-app.yaml` (see [App Centre manifest](app_manifest.md)), commit, then publish the release again. See [migration_0_1_24.md](migration_0_1_24.md). +The release reads `distribution.platforms` in `labconstrictor-app.yaml` to decide which installers to build. It stops when the file is not valid YAML, when `platforms` is not a list, or when it lists none of the systems the release can build: `windows-x86_64`, `linux-x86_64`, `macos-arm64` and `macos-x86_64`. The log of the step says which. Fix `labconstrictor-app.yaml` (see [Describe your app for the App Centre](app_manifest.md)), commit, then publish the release again. ## "The notebooks ask for incompatible package versions" -The **Run merge script** step of **Updates on notebook change**, or the `merge_requirements.py --check` command of a release, stops when notebooks pin a package to different versions, or ask for versions that no single version meets. Its log lists the package, each notebook and its requirement. Make the notebooks agree, or decide in `requirements_overrides.yaml` which requirement every notebook gets and why, then push it: the workflow runs again. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package) and [migration_0_1_31.md](migration_0_1_31.md). +The **Run merge script** step of **Updates on notebook change**, or the `merge_requirements.py --check` step of a release, stops when notebooks pin a package to different versions, or ask for versions that no single version meets. Its log lists the package, each notebook and its requirement. Make the notebooks agree, or decide in `requirements_overrides.yaml` which requirement every notebook gets and why, then push it: the workflow runs again. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package). -If the template synchronization to 0.1.31 created `requirements_overrides.yaml`, its entries keep the versions your app installed until now (the newest of the pins). Check each one with every notebook that uses the package, and replace its reason with yours. +If a template update created `requirements_overrides.yaml` for you, its entries keep the versions your app installed until then (the newest of the pins). Check each one with every notebook that uses the package, and replace its reason with yours. ## Publishing to PyPI fails From 4177e7aca0f01fd2e6e1c17caee82b8660a65305 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:24:19 +0000 Subject: [PATCH 07/12] Docs: app_manifest drops a template-version aside and a link to the maintainers' site Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- .tools/docs/app_manifest.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/.tools/docs/app_manifest.md b/.tools/docs/app_manifest.md index c5b787b..a898d49 100644 --- a/.tools/docs/app_manifest.md +++ b/.tools/docs/app_manifest.md @@ -115,7 +115,7 @@ The App Centre asks for a few optional fields: `status`, `quickstart`, `screensh | `colab` | A list of Google Colab notebooks, each with a `label` and a `url` on `colab.research.google.com`. Only the notebooks you list are shown. | | `pip` | The name of your package on PyPI. | -`platforms` also decides which installers your releases build (template 0.1.24 or later). Leave a system out when your app cannot run there. Without `platforms`, every installer is built: `windows-x86_64`, `linux-x86_64`, `macos-arm64` (Apple silicon) and `macos-x86_64` (Intel Macs). `windows-arm64` and `linux-arm64` are accepted, but no installer is built for them. +`platforms` also decides which installers your releases build. Leave a system out when your app cannot run there. Without `platforms`, every installer is built: `windows-x86_64`, `linux-x86_64`, `macos-arm64` (Apple silicon) and `macos-x86_64` (Intel Macs). `windows-arm64` and `linux-arm64` are accepted, but no installer is built for them. ### `hosts`: where your tools are offered @@ -155,7 +155,7 @@ The **Check App Centre manifest** workflow runs when you change the file and whe ## Check it yourself -To get an answer before you push, you have two more ways: +To check the file before you push: 1. **On your computer.** From the root of your repository: @@ -188,8 +188,6 @@ The rules themselves are in the [schema](https://cellmigrationlab.github.io/LabC Having the file does not list your app by itself. To list it, [submit your repository](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/) to the App Centre. You do this once: later releases appear by themselves. -The technical rules for `hosts` and `host_requirements` are in the [LabConstrictor-Tools manifest reference](https://cellmigrationlab.github.io/LabConstrictor-Tools/MANIFEST/). - ---
From 7a712cd6c7f21206f128cbb40d9e93d9460cb232 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:25:28 +0000 Subject: [PATCH 08/12] Docs: workflow_status no longer says workflows run on other branches The workflows run on pushes to main (and by hand), not on other branches, so the advice to test a big update on a branch could not work: upload one notebook at a time instead. The page also names the workflows and when the log artifact exists. installer_images: plainer text. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- .tools/docs/installer_images.md | 18 +++++++++--------- .tools/docs/workflow_status.md | 27 ++++++++------------------- 2 files changed, 17 insertions(+), 28 deletions(-) diff --git a/.tools/docs/installer_images.md b/.tools/docs/installer_images.md index e17f9c6..ef2930a 100644 --- a/.tools/docs/installer_images.md +++ b/.tools/docs/installer_images.md @@ -1,16 +1,16 @@ # Customise the installer images -The generated installer and desktop app can be customised with you own images. This will help to give your app a more professional look and feel. This customisation is optional and can be done when initialising your repository or at any time later. +You can brand the installer and the app's shortcut with your own images. This is optional. Upload them when you [initialise your repository](initialise_repository.md); the form resizes them to the sizes below. -You can provide the following images for customisation: +You can provide these images: -| Image Type | Recommended Size | Format | Description | +| Image | Recommended size | Format | Where it appears | |------------|------------------|--------|-------------| -| Logo | 256x256 pixels | PNG | This image will be used in the executable installer and on the created desktop app. | -| Banner | 164x314 pixels | PNG | This vertical image will be used as a banner in the installer. | -| Header | 150x57 pixels | PNG | This image will be used as the header in the installer. | +| Logo | 256x256 pixels | PNG | The installer and the app's shortcut. | +| Banner | 164x314 pixels | PNG | The vertical banner of the installer. | +| Header | 150x57 pixels | PNG | The header of the installer. | -When preparing your images, please ensure they meet the recommended size and format for optimal display. Here are some examples of custom images used in an installer: +Images in the recommended size display best. Here are the images of the LabConstrictor installer as examples: ## Logo ![LabConstrictor Logo](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/LabConstrictor_Logo.png) @@ -23,13 +23,13 @@ When preparing your images, please ensure they meet the recommended size and for ## Default installer -In case you do not provide any images during the initialisation of your repository, default placeholder images will be used: +Without your own images, the installer uses default images: ![Default Installer Images](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Customisation_Default.png) ## Customised installer -When you provide your own images, the installer will reflect your custom branding: +With your own images: ![Customised Installer Images](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Customisation_Custom.png) diff --git a/.tools/docs/workflow_status.md b/.tools/docs/workflow_status.md index edd8476..7115b94 100644 --- a/.tools/docs/workflow_status.md +++ b/.tools/docs/workflow_status.md @@ -1,36 +1,25 @@ # Check the status of GitHub workflows -When you upload a notebook or make a release, GitHub Actions starts a workflow to check your code and build the installers. The template synchronization workflow additionally requires the one-time [`LABCONSTRICTOR_SYNC_TOKEN` setup](template_synchronization.md). +GitHub Actions runs workflows in your repository: when a notebook or its requirements change (**Updates on notebook change**), when the code in `src/` changes (**Updates on external code change**), when you publish a release (**Build Release Installers**) and every week for template updates (**Sync with Template Repository**, which needs the one-time [`LABCONSTRICTOR_SYNC_TOKEN` setup](template_synchronization.md)). ## 1. Monitor the progress -1. Go to the **Actions** tab in your GitHub repository. -2. You’ll see a list of recent workflows. Find the one that matches your latest commit or release. -3. Check the status icon next to the workflow name: +1. Go to the **Actions** tab of your repository. +2. Find the run that matches your latest change or release. +3. Check its status icon: ![GitHub Actions Status Icons](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/actions_status_icons.png) ## 2. How to debug a failure -If the workflow fails, don’t worry. The system creates an error log that’s ready for you to use. +1. Click the failed run, then the red step: its log says what went wrong. +2. If the run has an **Artifacts** section at the bottom of its page, download the log file there (a plain `.log` text file, nothing to unzip). It holds the error, the workflow and the script that failed, with instructions at the top for an AI assistant: paste the whole file into one (such as ChatGPT, Gemini or Claude) and it explains the error and how to fix your notebook or `requirements.yaml`. -1. **Download the Log:** - * Click on the failed workflow run. - * Scroll down to the bottom of the page to the **Artifacts** section. - * Download the log file listed there (it is a plain `.log` text file, nothing to unzip). - -2. **Copy & Paste into AI:** - * Open the log file in any text editor. - * **This file is already formatted as a prompt.** It includes all the context and error details you need. - * Just **copy all the text** and paste it into your preferred AI tool (like ChatGPT, Gemini, or Claude). The AI will explain the error and show you how to fix your notebook or `requirements.yaml`. - ---- +For known errors, see [Troubleshooting repository setup](troubleshooting.md). ### Best practice for large updates -If you’re planning a big update, like changing several notebooks or adding complex dependencies, don’t push straight to the main branch. - -Instead, **create a new branch**, make your changes there, and check that the workflows pass (✅) before merging into the main branch. This helps keep your live app working. +The workflows run only on your main branch, so a change is checked once it is merged. For a big update, such as several notebooks or new dependencies, upload one notebook at a time and wait for the green tick before the next: a failure then points to one change. --- From c356df62ee283328c2db7375b53cf0be27aa61c3 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:29:52 +0000 Subject: [PATCH 09/12] Docs: install, tools_bridge and template_synchronization get the same pass install.md: 'Before you start', 'Check that it worked' and 'If something does not work' (the site's checks for a critical guide); the system sections keep their headings. tools_bridge.md opens with what the reader does, and links to the Tools operations page instead of the maintainers' paragraph on moving the pin. template_synchronization.md: footer links match its place in the docs index, plus a check step. The PyPI sections lose their design-note links; app_manifest links the protocol page on the website. Shipped to apps by the 0.1.37 migration (next commits). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- .tools/docs/app_manifest.md | 4 +- .tools/docs/external_code_upload.md | 2 +- .tools/docs/install.md | 27 ++++++--- .tools/docs/template_synchronization.md | 60 ++++++++++---------- .tools/docs/tools_bridge.md | 73 ++++++++++++------------- .tools/docs/troubleshooting.md | 2 +- 6 files changed, 89 insertions(+), 79 deletions(-) diff --git a/.tools/docs/app_manifest.md b/.tools/docs/app_manifest.md index a898d49..b588792 100644 --- a/.tools/docs/app_manifest.md +++ b/.tools/docs/app_manifest.md @@ -142,7 +142,7 @@ host_requirements: - Name only `napari`, `fiji` or `qupath`: the notebook ships with your app and needs no plugin. - Each needs `min_version`, `features`, or both. `required: true` makes an older plugin refuse your tools instead of warning; use it only when they really fail there. - Write it as a block, as above. The installer passes this file to `labconstrictor-tools register`, which refuses a malformed block (a misspelt host or key, a version like `latest`); `labconstrictor-tools check --module _lc_tools --app-manifest labconstrictor-app.yaml` shows what it read. -- The feature ids and the rule are in the [LabConstrictor-Tools documentation](https://github.com/CellMigrationLab/LabConstrictor-Tools/blob/main/docs/PROTOCOL.md#host-requirements-which-plugin-an-app-needs). +- The feature ids and the rule are in [the protocol reference](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/protocol/#host-requirements-which-plugin-an-app-needs). ## The automatic check @@ -192,7 +192,7 @@ Having the file does not list your app by itself. To list it, [submit your repos
-[← Previous](initialise_repository.md)            +[← Previous](installer_images.md)            [🏠 Home](README.md)            [Next →](external_code_upload.md) diff --git a/.tools/docs/external_code_upload.md b/.tools/docs/external_code_upload.md index 6a5f1c6..c19858c 100644 --- a/.tools/docs/external_code_upload.md +++ b/.tools/docs/external_code_upload.md @@ -110,7 +110,7 @@ Delete the variable `PYPI_PUBLISH` (**Settings** > **Secrets and variables** > * - **A version can be uploaded only once**, even after it was deleted from PyPI. The workflow checks this before it builds anything and stops with a clear message; to publish a fix, make a new release with a higher version. - **The release writes its version into `setup.py`** (the "Update version" commit of the release workflow), so the file and PyPI agree. - **To approve each upload by hand**, open **Settings** > **Environments** > **pypi** (GitHub creates it at the first run) and add **Required reviewers**. -- **A repository that already publishes to PyPI with a workflow of its own** does not get `publish_pypi.yml` from the template update, so nothing is uploaded twice. See [the design note of template 0.1.25](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_25.md). +- **A repository that already publishes to PyPI with a workflow of its own** does not get `publish_pypi.yml` from the template update, so nothing is uploaded twice. - If the workflow fails, see [Troubleshooting](troubleshooting.md#publishing-to-pypi-fails). --- diff --git a/.tools/docs/install.md b/.tools/docs/install.md index e4fcc0b..d0c84d5 100644 --- a/.tools/docs/install.md +++ b/.tools/docs/install.md @@ -1,13 +1,12 @@ # Install an app -Installing takes about 6-8 minutes and you only do it once. You need an internet connection while installing: the installer downloads the app's Python packages. Download the installer for your system from the app's page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) (or from the app's GitHub release) and follow the steps for your system. +Download the installer for your system from the app's page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) (or from the app's GitHub release), then follow the steps for your system below. You install an app once; it can take several minutes. > **Check where it comes from.** The installers are not code-signed yet, so your system will warn you. Download only from the app's own GitHub release (the address starts with `https://github.com/` followed by the app's owner and repository, as shown on the app's page), and run it only if you trust that owner. A listing in the App Centre checks that the files come from the app's repository; it is not a security audit. -> A command prompt window opens during installation on Windows; this is normal, do not close it. - -## Before you install +## Before you start +- **Internet connection.** The installer downloads the app's Python packages while it installs. - **Install path.** The install path must contain no space: the installer refuses a path with a space. Use a path such as `C:\LabConstrictor\` on Windows or `~/labconstrictor/` on macOS and Linux. ## Install on Windows @@ -17,12 +16,13 @@ Installing takes about 6-8 minutes and you only do it once. You need an internet ![Windows protected your PC: click More info, then Run anyway](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Windows_Protected_your_PC.png) -3. Follow the on-screen prompts. Launch the app from the Start Menu or your desktop. +3. Follow the on-screen prompts. A command prompt window opens during the installation: this is normal, do not close it. +4. Launch the app from the Start Menu or your desktop. ## Install on a Mac 1. Choose your file: open the Apple menu, then About This Mac. If the Chip or Processor says Intel, download the Intel installer; if it says M1, M2 or similar, download the Apple Silicon one. -2. Double-click the `.pkg` file. If macOS refuses to open it, go to System Settings, Privacy & Security, scroll down to the message about the package and click "Open Anyway" (it appears only after you tried to open the file once). If you do not see it, try opening the file again, then check this page again. +2. Double-click the `.pkg` file. If macOS refuses to open it, go to System Settings, Privacy & Security, scroll down to the message about the package and click "Open Anyway". The button appears only after you have tried to open the file once. 3. Follow the prompts (we recommend "Install only for me"). Launch the app from your Applications folder. ## Install on Linux @@ -31,9 +31,18 @@ Installing takes about 6-8 minutes and you only do it once. You need an internet 2. Open a terminal in the download folder and run `bash` followed by the name of the file you downloaded, for example: `bash MyApp-0.1.0-Linux-x86_64.sh` 3. Follow the prompts, then launch the app from your applications menu. +## Check that it worked + +Open the app. A terminal window opens, then JupyterLab opens in your web browser with the app's Welcome notebook. What to do next: [Use notebooks after installation](notebook_usage.md). + +## If something does not work + +- The installer writes what it did to `menuinst_debug.log` in the install folder. +- See [Troubleshooting an installed app](troubleshooting_installed_app.md), or start from [Find your problem](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/help/). + ## Update an installed app -- **macOS and Windows.** On macOS and Windows, update an app by [uninstalling the old version](#uninstall-an-app) first and then installing the new one: the installer does not install over an existing install. On macOS, if you already ran the new installer over the old version and it stopped or reported a failure at the end, move only the old app shortcut (for example `~/Applications/MyApp.app`) to the Bin, keep the app's folder in your home folder, and run the installer again ([known issue](https://github.com/CellMigrationLab/LabConstrictor/issues/34)). +- **macOS and Windows.** On macOS and Windows, update an app by [uninstalling the old version](#uninstall-an-app) first and then installing the new one: the installer does not install over an existing install. On macOS, if you already ran the new installer over the old version and it stopped or reported a failure at the end, move only the old app shortcut (for example `~/Applications/MyApp.app`) to the Bin, keep the app's folder in your home folder, and run the installer again. - **Linux.** On Linux, running the installer with `-u` updates in place only if the previous install finished; otherwise delete `/pkgs` or uninstall the app and install it again. ## Uninstall an app @@ -45,10 +54,10 @@ Uninstalling deletes the app's install folder and everything in it: move anythin ## Where the app is listed -If the app ships tools for napari, Fiji or QuPath, the installer registers them with LabConstrictor Tools and passes the `hosts:` line of the app's `labconstrictor-app.yaml` (the installer bundles that file). A host lists the app only if the line names it: with `hosts: [notebook, napari]` the app is listed in napari, and not in Fiji or QuPath. Without the file, or without a `hosts:` line, the app is registered without hosts, every host lists it, and `menuinst_debug.log` in the install folder says so (`'' declares no hosts, so it is listed in every host; ...`). +If the app ships tools for napari, Fiji or QuPath, the installer registers them with LabConstrictor Tools, with the `hosts:` line of the app's `labconstrictor-app.yaml`. A program lists the app only if that line names it: with `hosts: [notebook, napari]` the app is listed in napari, and not in Fiji or QuPath. Without a `hosts:` line, every program lists the app, and `menuinst_debug.log` in the install folder says so (`'' declares no hosts, so it is listed in every host; ...`). To run the tools, install the plugin for your image software once: see [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). ## Next -Open the app and start working: [Use notebooks after installation](notebook_usage.md). If something goes wrong, see [Troubleshooting an installed app](troubleshooting_installed_app.md). +Open the app and start working: [Use notebooks after installation](notebook_usage.md). diff --git a/.tools/docs/template_synchronization.md b/.tools/docs/template_synchronization.md index 1c512ea..d9c0d42 100644 --- a/.tools/docs/template_synchronization.md +++ b/.tools/docs/template_synchronization.md @@ -1,37 +1,36 @@ # Enable automatic LabConstrictor template updates -LabConstrictor periodically checks the main template for improvements. When an update is available, the **Sync with Template Repository** workflow prepares the changes in a pull request so you can review and merge them safely. +The **Sync with Template Repository** workflow checks the LabConstrictor template every week. When a newer template version exists, it opens a pull request in your repository with the changes, for you to review and merge. -You will need to do a one-time GitHub setup to create a token that allows LabConstrictor to update your repository. This token described below is limited to the repository you select. LabConstrictor does not need access to your other repositories. +To open that pull request, the workflow needs a token that you create once and save in your repository. The token gives access only to the repository you select, not to your other repositories. -## What do I need to do? +## What you need -Follow the same instructions that are given in the following video and instructions below. +- Admin access to your app's repository on GitHub (to add a secret). ## Step 1: Create the synchronization token ![GIF showing the token creation](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Synchronisation_Token_Creation.gif) -Follow steps on the GIF or click on [this link](https://github.com/settings/personal-access-tokens/new?name=LabConstrictor+Sync&description=Allows+LabConstrictor+to+prepare+template+update+pull+requests.&expires_in=365&contents=write&pull_requests=write&workflows=write) and follow the steps below: +Open [this link](https://github.com/settings/personal-access-tokens/new?name=LabConstrictor+Sync&description=Allows+LabConstrictor+to+prepare+template+update+pull+requests.&expires_in=365&contents=write&pull_requests=write&workflows=write), which fills in most of the form, then: -1. Under **Resource owner**, select the owner of your LabConstrictor repository. -2. Under **Repository access**, select **Only select repositories**. -3. Select your LabConstrictor repository. -4. Choose an expiration period that suits you. The prefilled suggestion is 365 days. -5. Confirm these repository permissions: +1. Under **Resource owner**, select the owner of your repository. +2. Under **Repository access**, select **Only select repositories**, then select your repository. +3. Choose an expiration period. The link suggests 365 days. +4. Check these repository permissions: - **Contents:** Read and write - **Pull requests:** Read and write - **Workflows:** Read and write -6. Select **Generate token**. -7. Copy the generated token. +5. Select **Generate token**. +6. Copy the token. -> GitHub shows the complete token only once. Keep the page open until you have saved it in Step 2. +> GitHub shows the token only once. Keep the page open until you have saved it in Step 2. ## Step 2: Save the token as a repository secret ![GIF showing the secret creation](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Synchronisation_Secret_Creation.gif) -1. Open your LabConstrictor repository. +1. Open your repository. 2. Select **Settings**. 3. In the left sidebar, select **Secrets and variables**, then **Actions**. 4. Select **New repository secret**. @@ -44,39 +43,44 @@ Follow steps on the GIF or click on [this link](https://github.com/settings/pers 6. Paste the token into the **Secret** field. 7. Select **Add secret**. -> GitHub encrypts repository secrets. The token will not be displayed in the repository or in normal workflow logs. +GitHub encrypts repository secrets: the token is not shown in the repository or in the workflow logs. -## Step 3 (situational): One-time step for repositories created before template version 0.1.12 +## Check that it worked -An older synchronization workflow does not yet reference `LABCONSTRICTOR_SYNC_TOKEN`. If you already saw an error saying that a GitHub App cannot create or update a workflow without `workflows` permission, make this small edit once: +Open the **Actions** tab, select **Sync with Template Repository** and click **Run workflow**. The run ends with a green tick. If a newer template version exists, a pull request titled "Sync template to version ..." appears in the **Pull requests** tab: merge it as described in [Accept a pull request](accept_pull_request.md). + +## Repositories created before template version 0.1.12 + +The older synchronization workflow does not use `LABCONSTRICTOR_SYNC_TOKEN`. If a run failed with an error saying that a GitHub App cannot create or update a workflow without `workflows` permission, edit the workflow once: 1. Open [`.github/workflows/sync_template.yml`](../../.github/workflows/sync_template.yml) in your repository. 2. Select the pencil icon to edit the file. -3. Copy and paste all the lines from the [LabConstrictor original workflow](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.github/workflows/sync_template.yml). - +3. Replace all its lines with those of the [template's workflow](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.github/workflows/sync_template.yml). 4. Select **Commit changes** and commit directly to the default branch. 5. Run **Sync with Template Repository** again. -The migration will then install the complete updated workflow automatically. This manual edit is only needed once for repositories whose existing workflow predates token integration. +The next template update then keeps the workflow up to date by itself. ## Renewing an expired token -When the token expires: +When the token expires, runs fail with an authentication error such as "Bad credentials". Then: -1. Create a replacement token using Step 1. +1. Create a new token as in Step 1. 2. Open **Settings → Secrets and variables → Actions**. 3. Select `LABCONSTRICTOR_SYNC_TOKEN`. -4. Select **Update secret** and paste the replacement token. -5. Run synchronization again. +4. Select **Update secret** and paste the new token. +5. Run **Sync with Template Repository** again. + +## If something does not work -You do not need to edit the workflow again. +See [Synchronisation is failing on GitHub Actions](troubleshooting.md#synchronisation-is-failing-on-github-actions). ---
-[← Create repository](create_repository.md)            -[🏠 Documentation home](README.md)            -[Initialise repository →](initialise_repository.md) +[← Previous](keep_app_up_to_date.md)            +[🏠 Home](README.md)            +[Next →](notebook_portability.md)
diff --git a/.tools/docs/tools_bridge.md b/.tools/docs/tools_bridge.md index d283aa6..f96331e 100644 --- a/.tools/docs/tools_bridge.md +++ b/.tools/docs/tools_bridge.md @@ -1,18 +1,20 @@ # 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 -function signatures. Nothing changes for apps that do not declare tools. +Turn functions of your app's Python package into **tools** that people run in napari, Fiji and QuPath, and from the command line. Each tool gets a form made from its function signature. You declare the tools in your repository; the installer registers them on the user's computer. Apps that declare no tools are not affected. -This page covers what the template does: where you declare the tools and what the installer does with them. Two other guides cover the rest: +To expose your app's tools: -- [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/): the inputs - and outputs a tool can have, how to lay out its form, what each program supports, and how to test a tool. -- [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/): what the people - who install your app do to run its tools, with the install steps of the - [napari plugin](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/napari/), the - [Fiji plugin](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/fiji/) and the - [QuPath extension](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/qupath/). +1. Put your Python code in `src/` (see [Upload external code](external_code_upload.md)). +2. Declare the tools in a `_lc_tools` module, as shown below. +3. Name the programs your tools work in under `hosts:` in `labconstrictor-app.yaml`. +4. Test the tools, then publish a release. + +How to write a tool, with its inputs, outputs, form layout and tests, is in [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/). What the people who install your app do to run the tools is in [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). + +## What you need + +- An app repository made from this template, with your Python package in `src//`. +- Python functions with type annotations that you want to offer as tools. ## Declare your tools @@ -31,17 +33,17 @@ This page covers what the template does: where you declare the tools and what th ``` Keep the module light: it is imported to read the tool list, so heavy imports at the top slow every start. -2. Import `labconstrictor_tools` only in `_lc_tools`, or inside functions, if you can. The rest of your package then also works - where LabConstrictor Tools is not installed: a notebook run on Google Colab, a copy of the package used elsewhere, or an installation where - Tools failed to install. An import at the top of your package does not stop the installation, because the installer installs Tools before - it checks that your package can be imported. +2. If you can, import `labconstrictor_tools` only in `_lc_tools`, or inside functions. The rest of your package then also + works where LabConstrictor Tools is not installed: a notebook on Google Colab, a copy of the package used elsewhere, or an installation + where Tools failed to install. 3. Name the programs your tools work in under `hosts:` in `labconstrictor-app.yaml`: see [Describe your app for the App Centre](app_manifest.md). -4. Test your tools before you publish a release, as [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/) - shows (`labconstrictor-tools check` and `labconstrictor-tools test`). + napari, Fiji and QuPath list your app only if `hosts:` names them. +4. Test your tools with `labconstrictor-tools check` and `labconstrictor-tools test`, as + [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/) shows. ## What the installer does -The installer's `post_install` step: +When someone installs your app, the installer: 1. installs your package; 2. if your package has a `_lc_tools` module, installs LabConstrictor Tools; @@ -49,33 +51,28 @@ The installer's `post_install` step: 4. registers the app (`labconstrictor-tools register ...`) with the version from the `version:` line of `construct.yaml` and the hosts of `labconstrictor-app.yaml`. -When the app is uninstalled, `pre_uninstall` unregisters it. - -A failure in step 2 or 4 is written as a `WARNING` to `menuinst_debug.log` in the install folder, the registration is skipped, and the -installation goes on. The one exception is a package that needs Tools to be imported: then the import check of step 3 fails, as it should. - -The Windows step (`post_install.bat`) runs in the template's automated tests on a Windows machine, and people have installed apps on Windows -and macOS from a clean system. +When the app is uninstalled, it is unregistered. -### Which LabConstrictor Tools the installer installs +If step 2 or 4 fails, the installer writes a `WARNING` to `menuinst_debug.log` in the install folder, skips the registration and finishes +the installation. The exception is a package that imports `labconstrictor_tools` at the top: then the import check of step 3 fails. -LabConstrictor Tools is not on PyPI yet. The installer downloads the GitHub archive of one release tag of LabConstrictor-Tools, a plain zip -file, so the user's computer does not need git. The tag is pinned: two installers built from the same app release install the same Tools, -and a change to Tools does not reach new installations until the pin is moved on purpose. Template updates move the pin in your app. +The installer installs one fixed release of LabConstrictor Tools: the tag in `LC_TOOLS_PIN` of +[app/bash_bat_scripts/post_install.sh](../../app/bash_bat_scripts/post_install.sh) and +[app/bash_bat_scripts/post_install.bat](../../app/bash_bat_scripts/post_install.bat). Template updates move it. To install Tools from +another source (a wheel, a git URL or a mirror), set the environment variable `LC_TOOLS_SPEC` when the installer runs; it replaces the pin. +How Tools releases are made and pinned is in +[Operations](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/tools-operations/#pinning-tools-in-app-installers). -The tag is the value of `LC_TOOLS_PIN` in both scripts: -[app/bash_bat_scripts/post_install.sh](../../app/bash_bat_scripts/post_install.sh) (`LC_TOOLS_PIN="..."`) and -[app/bash_bat_scripts/post_install.bat](../../app/bash_bat_scripts/post_install.bat) (`SET "LC_TOOLS_PIN=..."`). +## Check that it worked -To install Tools from somewhere else, set the environment variable `LC_TOOLS_SPEC` when the installer runs: a wheel, a git URL, a mirror, or -the name `labconstrictor-tools` once it is on PyPI. It replaces the pin completely. +After you install a release of your app: -**Move the pin (template maintainers).** Create and test the tag in LabConstrictor-Tools (the procedure is in its `docs/OPERATIONS.md`). -Change `LC_TOOLS_PIN` in both scripts of the template, and in the copies under `.template_sync/resources/` of the latest migration if it has -them (the test `test_resources_are_identical_to_the_template_files` fails when they differ). Then write a migration that changes the string in -the apps' scripts, and bump `template_version`. +- `menuinst_debug.log` in the install folder says `Tools registered`. +- `labconstrictor-tools list` shows your app and its tools. +- Your app appears in the programs you named under `hosts:`, once their plugin is installed. ## If something does not work - `menuinst_debug.log` in the app's install folder says what the installer did with your tools. - `labconstrictor-tools doctor` checks the Tools installation, and `labconstrictor-tools logs` shows its log. +- Other problems and their fixes: [Operations](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/tools-operations/). diff --git a/.tools/docs/troubleshooting.md b/.tools/docs/troubleshooting.md index 1fbcfa0..5f68a97 100644 --- a/.tools/docs/troubleshooting.md +++ b/.tools/docs/troubleshooting.md @@ -61,7 +61,7 @@ The workflow **Publish the Python package to PyPI** (`publish_pypi.yml`) runs at | `setup.py still has the template placeholder ...` | Replace the placeholder in `setup.py` (the log says which), commit, and publish a new release. | | The upload job waits | The `pypi` environment has required reviewers (Settings > Environments > pypi): one of them approves the upload in the run. | -After a fix, re-run the failed jobs of the run if nothing in the repository changed (a publisher fixed on pypi.org); otherwise publish a new release. See [the design note of template 0.1.25](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_25.md). +After a fix, re-run the failed jobs of the run if nothing in the repository changed (a publisher fixed on pypi.org); otherwise publish a new release. --- From dc20444d1547b38fccd0e39d4d520afc1eab9374 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:32:26 +0000 Subject: [PATCH 10/12] Template 0.1.37: migration that ships the rewritten user guides v0_1_36_to_v0_1_37.py replaces seventeen guides of .tools/docs whole, only when the app's copy is still the 0.1.36 template file (LF comparison, the app's line endings kept, SKIPPED otherwise, nothing created or deleted). external_code_upload.md is also recognised with the app's package name in place of PYTHON_PROJ_NAME. Resources: the new pages and previous/ (the 0.1.36 pages). Design note migration_0_1_37.md (not listed in the index). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- .template_sync/manifest.yaml | 5 +- .../migrations/v0_1_36_to_v0_1_37.py | 127 +++++++++++ .../.tools/docs/accept_pull_request.md | 27 +++ .../.tools/docs/app_manifest.md | 200 +++++++++++++++++ .../.tools/docs/before_getting_started.md | 52 +++++ .../.tools/docs/create_repository.md | 33 +++ .../.tools/docs/executable_creation.md | 55 +++++ .../.tools/docs/external_code_upload.md | 125 +++++++++++ .../.tools/docs/initialise_repository.md | 55 +++++ .../v0_1_36_to_v0_1_37/.tools/docs/install.md | 63 ++++++ .../.tools/docs/installer_images.md | 45 ++++ .../.tools/docs/notebook_requirements.md | 115 ++++++++++ .../.tools/docs/notebook_upload.md | 193 +++++++++++++++++ .../.tools/docs/notebook_usage.md | 51 +++++ .../.tools/docs/template_synchronization.md | 86 ++++++++ .../.tools/docs/tools_bridge.md | 78 +++++++ .../.tools/docs/troubleshooting.md | 75 +++++++ .../docs/troubleshooting_installed_app.md | 69 ++++++ .../.tools/docs/workflow_status.md | 34 +++ .../.tools/docs/accept_pull_request.md | 35 +++ .../previous/.tools/docs/app_manifest.md | 202 ++++++++++++++++++ .../.tools/docs/before_getting_started.md | 52 +++++ .../previous/.tools/docs/create_repository.md | 45 ++++ .../.tools/docs/executable_creation.md | 41 ++++ .../.tools/docs/external_code_upload.md | 125 +++++++++++ .../.tools/docs/initialise_repository.md | 22 ++ .../previous/.tools/docs/install.md | 54 +++++ .../previous/.tools/docs/installer_images.md | 45 ++++ .../.tools/docs/notebook_requirements.md | 112 ++++++++++ .../previous/.tools/docs/notebook_upload.md | 178 +++++++++++++++ .../previous/.tools/docs/notebook_usage.md | 44 ++++ .../.tools/docs/template_synchronization.md | 82 +++++++ .../previous/.tools/docs/tools_bridge.md | 81 +++++++ .../previous/.tools/docs/troubleshooting.md | 75 +++++++ .../docs/troubleshooting_installed_app.md | 68 ++++++ .../previous/.tools/docs/workflow_status.md | 45 ++++ .tools/docs/migration_0_1_37.md | 37 ++++ 37 files changed, 2830 insertions(+), 1 deletion(-) create mode 100644 .template_sync/migrations/v0_1_36_to_v0_1_37.py create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/accept_pull_request.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/app_manifest.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/before_getting_started.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/create_repository.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/executable_creation.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/external_code_upload.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/initialise_repository.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/install.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/installer_images.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_requirements.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_upload.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_usage.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/template_synchronization.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/tools_bridge.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/troubleshooting.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/troubleshooting_installed_app.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/workflow_status.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/accept_pull_request.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/app_manifest.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/before_getting_started.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/create_repository.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/executable_creation.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/external_code_upload.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/initialise_repository.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/install.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/installer_images.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_requirements.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_upload.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_usage.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/template_synchronization.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/tools_bridge.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/troubleshooting.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/troubleshooting_installed_app.md create mode 100644 .template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/workflow_status.md create mode 100644 .tools/docs/migration_0_1_37.md diff --git a/.template_sync/manifest.yaml b/.template_sync/manifest.yaml index 8711dbd..6f4bced 100644 --- a/.template_sync/manifest.yaml +++ b/.template_sync/manifest.yaml @@ -1,4 +1,4 @@ -template_version: 0.1.36 +template_version: 0.1.37 migrations: - from: 0.0.0 to: 0.0.1 @@ -114,3 +114,6 @@ migrations: - from: 0.1.35 to: 0.1.36 script: migrations/v0_1_35_to_v0_1_36.py + - from: 0.1.36 + to: 0.1.37 + script: migrations/v0_1_36_to_v0_1_37.py diff --git a/.template_sync/migrations/v0_1_36_to_v0_1_37.py b/.template_sync/migrations/v0_1_36_to_v0_1_37.py new file mode 100644 index 0000000..6b07528 --- /dev/null +++ b/.template_sync/migrations/v0_1_36_to_v0_1_37.py @@ -0,0 +1,127 @@ +"""Template 0.1.36 -> 0.1.37: the user guides are rewritten for the website's three tracks. + +Design note: https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_37.md + +The guides were checked against the template, the repository form and the installer, and rewritten to be shorter and plainer. The guides a +first-time reader follows to the end (install, initialise the repository, generate requirements, upload a notebook, create the installers) +now say what you need, how to check that it worked and what to do if it does not. + +What this changes in an app repository: each guide in FILES is replaced by the 0.1.37 page when it is still the 0.1.36 template file +(compared with LF line endings; the file keeps its own line endings). A guide the app changed itself stays as it is (SKIPPED, with a note). +A missing guide is not created, and nothing is deleted. external_code_upload.md is also recognised with the app's Python package name in +place of PYTHON_PROJ_NAME (the repository form writes it there), and the new page gets the same name. The changes reach users with the +app's next release. +""" +from __future__ import annotations + +import re +from pathlib import Path +from typing import Any + + +DOCS_URL = "https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_37.md" +TAG = "[migration 0.1.37]" +RESOURCE_ROOT = Path(__file__).resolve().parents[1] / "resources" / "v0_1_36_to_v0_1_37" +PREVIOUS_ROOT = RESOURCE_ROOT / "previous" + +DOCS = Path(".tools/docs") +EXTERNAL_CODE_DOC = DOCS / "external_code_upload.md" + +# Files replaced whole, only when they are the 0.1.36 template file (compared with LF line endings). +FILES = tuple( + DOCS / name + for name in ( + "accept_pull_request.md", + "app_manifest.md", + "before_getting_started.md", + "create_repository.md", + "executable_creation.md", + "external_code_upload.md", + "initialise_repository.md", + "install.md", + "installer_images.md", + "notebook_requirements.md", + "notebook_upload.md", + "notebook_usage.md", + "template_synchronization.md", + "tools_bridge.md", + "troubleshooting.md", + "troubleshooting_installed_app.md", + "workflow_status.md", + ) +) + +# The placeholder the repository form replaces in a guide, by guide: the form writes the app's Python package name in place of it. +RENDERED = {EXTERNAL_CODE_DOC: "PYTHON_PROJ_NAME"} +IDENTIFIER = r"[A-Za-z_][A-Za-z0-9_]*" + + +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 filled_in_name(template_lf: str, text_lf: str, placeholder: str) -> str | None: + """The name written in `text_lf` everywhere `template_lf` has `placeholder` (the same name each time), or None when the texts differ + elsewhere.""" + if placeholder not in template_lf: + return None + parts = template_lf.split(placeholder) + pattern = re.escape(parts[0]) + f"(?P{IDENTIFIER})" + "".join(re.escape(part) + "(?P=name)" for part in parts[1:-1]) + pattern += re.escape(parts[-1]) + match = re.fullmatch(pattern, text_lf, flags=re.DOTALL) + return match.group("name") if match else None + + +def replaced_file(relative: Path, text_lf: str) -> tuple[str, str]: + """The 0.1.37 text of `relative` for the app's `text_lf`, and what was done. The text is unchanged when it is not the 0.1.36 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.37 page" + placeholder = RENDERED.get(relative) + if placeholder: + name = filled_in_name(new, text_lf, placeholder) + if name: + return text_lf, "already up to date" + name = filled_in_name(previous, text_lf, placeholder) + if name: + return new.replace(placeholder, name), f"replaced by the 0.1.37 page (with the package name {name})" + return text_lf, f"SKIPPED: customised (not the 0.1.36 template file), so it was left unchanged; compare it with the template's page. 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.37 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_36_to_v0_1_37/.tools/docs/accept_pull_request.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/accept_pull_request.md new file mode 100644 index 0000000..f0474f3 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/accept_pull_request.md @@ -0,0 +1,27 @@ +# Accept a pull request + +The repository initialiser, the notebook upload form and template updates all send their changes to your repository as a pull request. You accept a pull request by merging it. + +1. Open the **Pull requests** tab of your repository. + + ![Pull Request Tab](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/PR_tab.png) + +2. Click the title of the pull request to open it. The newest one is at the top. The **Files changed** tab shows what it changes. +3. Click the green **Merge pull request** button, then **Confirm merge**. +4. Optional: click **Delete branch** to remove the branch the pull request came from. + +![Accept a Pull Request GIF](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Accept_PR.gif) + +The merge can start a workflow in the **Actions** tab: see [Check the status of GitHub workflows](workflow_status.md). Template updates arrive this way once you have enabled [automatic template updates](template_synchronization.md). + + +--- + +
+ +[← Previous](initialise_repository.md)            +[🏠 Home](README.md)            +[Next →](notebook_requirements.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/app_manifest.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/app_manifest.md new file mode 100644 index 0000000..b588792 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/app_manifest.md @@ -0,0 +1,200 @@ +# Describe your app: the `labconstrictor-app.yaml` file + +`labconstrictor-app.yaml` is a small text file in the root of your repository. It says what your app is, in your own words. You write it once and keep it up to date yourself. + +Three things read it: + +- **The [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/)** builds your app's card and page from it. +- **Your release workflow** reads `platforms` to decide which installers to build. +- **Your installer** passes `hosts` and `host_requirements` to napari, Fiji and QuPath, so they know whether to list your app. + +Version numbers and download links are not in the file. They always come from your latest GitHub release. + +## Step 1: get the file + +The [repository initialiser](initialise_repository.md) asks for a one-sentence summary, the kind of app and the software it also works in. It adds the file to the initialisation pull request. Read it there and edit it if you like. + +If you skipped that section, or your repository is older than the file, create `labconstrictor-app.yaml` in the root of your repository and paste the minimal example below. The [Submit page](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/) also has a form that writes the file for you and checks it as you type. + +## Step 2: start with the minimal file + +These five fields are required. This file is complete and valid: + +```yaml +schema: 1 +name: My App +summary: Counts nuclei in 2D fluorescence images and saves a table. +kind: analysis +distribution: + installer: true +``` + +## Step 3: add what helps people choose your app + +A fuller example. Everything after `distribution` is optional. + +```yaml +# yaml-language-server: $schema=https://cellmigrationlab.github.io/LabConstrictor-Site/schema/labconstrictor-app.schema.json +schema: 1 +name: My App +summary: Counts nuclei in 2D fluorescence images and saves a table. +description: |- + A few paragraphs of plain text. + + Separate paragraphs with a blank line. +kind: analysis +hosts: [notebook, napari, qupath] +host_requirements: + napari: + min_version: 0.1.0-alpha.5 + why: Older plugins do not show the outlines + required: false +distribution: + installer: true + platforms: [windows-x86_64, macos-arm64, linux-x86_64] + colab: + - label: Notebook + url: https://colab.research.google.com/github/you/my-app/blob/main/notebooks/App/App.ipynb + pip: my-app +status: Available +license: MIT +authors: + - name: Ada Lovelace + orcid: 0000-0002-1825-0097 +doi: 10.1371/journal.pbio.3002740 +inputs: + - 2D TIFF images, one channel per file +outputs: + - Label masks and a CSV table +limitations: + - Not tested on 3D data +quickstart: + - Open the app and run the Welcome notebook. +categories: [nuclei, counting] +homepage: https://github.com/you/my-app +docs_url: https://github.com/you/my-app#readme +icon: app/logo/logo.png +screenshots: + - path: docs/screenshot.png + caption: The result table next to the segmented image +``` + +The first line lets editors with YAML support (for example VS Code) check the file as you type. Everything is plain text: no HTML and no Markdown. + +## The fields + +| Field | Required | What it does | Example | +|---|---|---|---| +| `schema` | Yes | The format version. Always `1`. | `1` | +| `name` | Yes | The name people know the app by (2 to 60 characters). | `My App` | +| `summary` | Yes | One sentence for the app card (20 to 200 characters). | `Counts nuclei in 2D images.` | +| `kind` | Yes | What the app is for. One of `analysis`, `segmentation`, `simulation`, `game`, `training`, `utility`. It drives the filter in the App Centre. | `analysis` | +| `distribution` | Yes | How people get the app. At least one of `installer`, `colab`, `pip`. See below. | `installer: true` | +| `hosts` | No | Where the app's tools run: `notebook`, `napari`, `fiji`, `qupath`. See below. | `[notebook, napari]` | +| `host_requirements` | No | The oldest napari, Fiji or QuPath plugin your tools need. See below. | | +| `description` | No | A few paragraphs for the app page (up to 2000 characters). | | +| `status` | No | `Experimental`, `Available` or `Deprecated`. | `Available` | +| `license` | No | The licence, as an SPDX name. | `MIT` | +| `authors` | No | A list of people: `name`, and optionally `orcid`. | `- name: Ada Lovelace` | +| `doi` | No | The DOI of the paper to cite, not of a software archive. The app page shows it as the citation. | `10.1371/journal.pbio.3002740` | +| `inputs`, `outputs`, `limitations` | No | Short lists for the app page: one to six lines of 5 to 200 characters each. | `- 2D TIFF images` | +| `quickstart` | No | Up to six short steps for a first run. | `- Open the app.` | +| `categories` | No | Up to six words a scientist would search for. | `[nuclei, counting]` | +| `homepage`, `docs_url` | No | Web addresses. They must start with `https://`. | | +| `icon` | No | A square PNG in your repository. SVG is not accepted. | `app/logo/logo.png` | +| `screenshots` | No | One to six pictures in your repository (PNG, JPG or GIF), each with a `path` and a `caption`. The caption is also the text for screen readers. | | + +The App Centre asks for a few optional fields: `status`, `quickstart`, `screenshots`, a licence, and `inputs` and `outputs` for analysis, segmentation and simulation apps. Without them your app is still listed; its page says "Not stated" or leaves that part out. + +### `distribution`: how people get the app + +| Key | What it does | +|---|---| +| `installer: true` | Your latest GitHub release carries the installers LabConstrictor builds. | +| `platforms` | The systems you support. Needs `installer: true`. Only these installers are built and offered. | +| `colab` | A list of Google Colab notebooks, each with a `label` and a `url` on `colab.research.google.com`. Only the notebooks you list are shown. | +| `pip` | The name of your package on PyPI. | + +`platforms` also decides which installers your releases build. Leave a system out when your app cannot run there. Without `platforms`, every installer is built: `windows-x86_64`, `linux-x86_64`, `macos-arm64` (Apple silicon) and `macos-x86_64` (Intel Macs). `windows-arm64` and `linux-arm64` are accepted, but no installer is built for them. + +### `hosts`: where your tools are offered + +This field matters only if your app [exposes tools](tools_bridge.md). napari, Fiji and QuPath list your app only if you name them here. Write the hosts you have tested the app in. + +- `hosts: [notebook]` means no plugin lists the app. Its tools still work in the notebook and on the command line. +- Without a `hosts` line, every plugin lists the app. Say what you mean instead. +- Names are lower case. The check refuses a misspelt, repeated or capitalised name. + +## Plugin versions your tools need (optional) + +If your tools rely on a fix or a feature of the napari, Fiji or QuPath plugin that older plugins lack, say so with `host_requirements`. People with an older plugin keep seeing your app, with one sentence saying which plugin to update and where; your app page on the App Centre lists the versions under "Plugin versions". + +```yaml +host_requirements: + qupath: + min_version: 0.1.0-alpha.7 # a release tag of the plugin, with or without v + features: [shapes_owner_v1] # optional: a host feature id + why: Replace keeps your own annotations # optional: one line shown to the person + fiji: + min_version: 0.1.0-alpha.7 +``` + +- Name only `napari`, `fiji` or `qupath`: the notebook ships with your app and needs no plugin. +- Each needs `min_version`, `features`, or both. `required: true` makes an older plugin refuse your tools instead of warning; use it only when they really fail there. +- Write it as a block, as above. The installer passes this file to `labconstrictor-tools register`, which refuses a malformed block (a misspelt host or key, a version like `latest`); `labconstrictor-tools check --module _lc_tools --app-manifest labconstrictor-app.yaml` shows what it read. +- The feature ids and the rule are in [the protocol reference](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/protocol/#host-requirements-which-plugin-an-app-needs). + +## The automatic check + +The **Check App Centre manifest** workflow runs when you change the file and when you publish a release: + +- If the file is missing, it shows a warning and passes. +- If the file is invalid, it fails and says what to fix. This never stops your installers from being built. +- It rejects fields it does not know (this catches typos, so the schema is not loosened); the template keeps its copy of the schema in step with the App Centre, see [Keep your app up to date](keep_app_up_to_date.md). +- It also checks that the icon and screenshots you name exist in the repository. + +## Check it yourself + +To check the file before you push: + +1. **On your computer.** From the root of your repository: + + ```bash + pip install pyyaml jsonschema + python .tools/python/check_app_manifest.py + ``` + +2. **In your browser.** Paste your values into the form on the [Submit page](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/). It checks them against the same schema. + +If your app exposes tools, also run `labconstrictor-tools check --module _lc_tools --app-manifest labconstrictor-app.yaml`. It prints the `hosts` and `host_requirements` it read, which is what the installer will register. + +The rules themselves are in the [schema](https://cellmigrationlab.github.io/LabConstrictor-Site/schema/labconstrictor-app.schema.json). Your repository has a copy in `.tools/schema/`, and the check uses that copy. + +## Common mistakes + +| What the check says, or what you see | Fix | +|---|---| +| A field "is not allowed" or is "unexpected" | The name is misspelt, or it is at the wrong level. For example `platforms` belongs under `distribution`. | +| `summary` is too short or too long | Write one sentence of 20 to 200 characters. | +| `platforms` without `installer` | Add `installer: true`. `platforms` only applies to installers. | +| The icon or a screenshot is "not found" | The path starts at the root of your repository, with no leading `/`. The file must be committed. | +| A Colab link is refused | The address must start with `https://colab.research.google.com/`. | +| `min_version: 0.2` is refused | YAML reads `0.2` as a number. Put it in quotes: `"0.2"`. | +| Your app is missing from napari, Fiji or QuPath | The host is not in `hosts`, or the app was installed before you added it. Publish a release and install it again. | +| The check passes but nothing changes in the App Centre | The App Centre reads the file from your default branch and updates once a day. | +| Text shows `**stars**` or tags | The fields are plain text. Remove Markdown and HTML. | + +## Get listed + +Having the file does not list your app by itself. To list it, [submit your repository](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/) to the App Centre. You do this once: later releases appear by themselves. + +--- + +
+ +[← Previous](installer_images.md)            +[🏠 Home](README.md)            +[Next →](external_code_upload.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/before_getting_started.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/before_getting_started.md new file mode 100644 index 0000000..fd974a6 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/before_getting_started.md @@ -0,0 +1,52 @@ +# 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. +- **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_36_to_v0_1_37/.tools/docs/create_repository.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/create_repository.md new file mode 100644 index 0000000..e2db347 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/create_repository.md @@ -0,0 +1,33 @@ +# Create your repository + +Your app lives in its own GitHub repository, made from the LabConstrictor template. + +1. Open the [LabConstrictor template on GitHub](https://github.com/CellMigrationLab/LabConstrictor). +2. Click the green **Use this template** button at the top right, then **Create a new repository**. + + ![Use template screenshot](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Use_Template.png) + +3. Fill in the details: + - **Include all branches:** leave it off. + - **Owner:** your personal account or your research group's organization. + - **Repository name:** a short name, for example `MyLabTools`. We recommend using it as your app's name when you initialise the repository. + - **Description** (optional): what your notebooks do, for example "Automated cell migration analysis". + - **Visibility:** **Public** to share your installers right away; **Private** to keep the code within your lab while you work on it. A private repository cannot be listed in the App Centre: make it public before you submit your app. +4. Click **Create repository**. + +Next: [Initialise your repository](initialise_repository.md). + +## Template updates (optional, later) + +The template keeps improving, and your repository can receive the changes as pull requests. Set this up after your first release: see [Keep your app up to date](keep_app_up_to_date.md). Until you do, the weekly **Sync with Template Repository** run stops with the error "Synchronization setup required" whenever a newer template version exists. + +--- + +
+ +[← Previous](before_getting_started.md)            +[🏠 Home](README.md)            +[Next →](initialise_repository.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/executable_creation.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/executable_creation.md new file mode 100644 index 0000000..b90ce74 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/executable_creation.md @@ -0,0 +1,55 @@ +# 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`). + +## Please check before proceeding + +Open the **Actions** tab of your repository and check that no workflow is running. If one is in progress, wait until it finishes: a release started while another workflow runs may build from files that are about to change. + +## 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 [Use notebooks after installation](notebook_usage.md). +- List your app in the App Centre: [Describe your app for the App Centre](app_manifest.md). +- Receive future template improvements as pull requests: [Keep your app up to date](keep_app_up_to_date.md). + + +--- + +
+ +[← Previous](notebook_upload.md)            +[🏠 Home](README.md)            +[Next →](installer_images.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/external_code_upload.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/external_code_upload.md new file mode 100644 index 0000000..c19858c --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/external_code_upload.md @@ -0,0 +1,125 @@ +# Upload external code + +If you want to use your own Python modules or scripts in Jupyter notebooks, follow these steps to upload them easily. + +## 1. Prepare your external code + +Organize your external code and follow Python packaging best practices. Set up the right folder structure, add an `__init__.py` file, and list any required dependencies. + +**Suggested Directory Structure:** + +```text +src/ +|-- PYTHON_PROJ_NAME/ +| |-- __init__.py +| |-- my_script.py +| |-- subpackage/ +| |-- __init__.py +``` + +### What goes in `__init__.py`? + +Think of `__init__.py` as the file that tells Python “this folder is a package”. + + If you leave it empty, that is perfectly fine—the package will still import correctly. When you want to make notebooks feel friendlier, you can re-export helper functions so users can discover them more easily: + +```python +# src/PYTHON_PROJ_NAME/__init__.py +from .my_script import run_analysis, load_config + +__all__ = ["run_analysis", "load_config"] +``` + +Each folder that you plan to import (for example, `src/subpackage/`) should also have its own `__init__.py`. Keep it empty unless you want to expose selected helpers from that subpackage. + +If you need further readings on `__init__.py`, check out this quick [Geeks for Geeks tutorial](https://www.geeksforgeeks.org/python/what-is-__init__-py-file-in-python/) or the [Real Python guide](https://realpython.com/python-init-py/). +## 2. Upload your external code to the repository + +Go to the src folder in your repository and upload your files or folders there. + +![Upload external code GIF](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Upload_src.gif) + +## 3. How to import into your notebook + +Once uploaded, your external code will be available to your notebooks as a package. To use it, import it as shown in the examples below: + +**Import the whole package:** +```python +import PYTHON_PROJ_NAME +``` + +If your folder under `src/` is called `celltools`, then `import celltools` will work because `src/celltools/__init__.py` exists. + +**Import function:** +```python +from PYTHON_PROJ_NAME import my_script +``` + +**Import submodule:** +```python +from PYTHON_PROJ_NAME.subpackage import submodule1 +``` + +## 4. Publish the code on PyPI (optional) + +The installer always puts your package into the app. You can also publish it on [PyPI](https://pypi.org), so that anyone can install it with `pip install`, in Google Colab or in their own Python. Each release then does both, with the same version: the GitHub Actions workflow `.github/workflows/publish_pypi.yml` builds the package and uploads it when you publish a release, next to the installers. + +It is **off until you turn it on**, and GitHub stores no password or token for it: PyPI trusts this repository's workflow directly ([trusted publishing](https://docs.pypi.org/trusted-publishers/)). + +**What is published** + +| | | +|---|---| +| Name | The `name=` of `setup.py`: the name of the package, given when the repository was initialised (unless you changed it). If `labconstrictor-app.yaml` has `distribution.pip`, it must be the same name. | +| Version | The release tag without the `v`: release `v1.2.0` publishes 1.2.0. | +| Code | Every package in `src/` (a folder with an `__init__.py`). | +| Dependencies | Each line of `requirements.txt`, as it is written (exact versions included). Options (`-r`, `--extra-index-url`), paths and URLs are left out, with a warning in the log: PyPI refuses dependencies given as URLs. | +| Description | `README.md` of the repository, shown on the PyPI page. | +| License | The `LICENSE` file. | + +### One-time setup + +1. **Check that the name is free.** Open `https://pypi.org/project//`. A "404 Not Found" page means nobody uses it. If it is taken, change `name=` in `setup.py` (and `distribution.pip`) and commit. +2. **Register this workflow on PyPI.** Log in to [pypi.org](https://pypi.org) (create an account if you have none; PyPI asks for two-factor authentication). Open your account menu > **Your projects** > **Publishing** ([pypi.org/manage/account/publishing](https://pypi.org/manage/account/publishing/)). Under **Add a new pending publisher**, choose the **GitHub** tab. The form has five fields; fill them in exactly: + - **PyPI Project Name:** the name of the package. + - **Owner:** the GitHub user or organisation that owns the repository (`CellMigrationLab` in `github.com/CellMigrationLab/MyApp`). + - **Repository name:** the repository (`MyApp`). + - **Workflow name:** `publish_pypi.yml` + - **Environment name:** `pypi` + + Click **Add**. The publisher appears under **Pending publishers** below the form. It does not reserve the name: the project is created by your first release. If the project already exists on PyPI and you own it, add the publisher in the project instead: **Your projects** > the project > **Manage** > **Publishing**. +3. **Turn it on in GitHub.** In the repository, open **Settings** > **Secrets and variables** > **Actions**, then the **Variables** tab (not **Secrets**: a secret cannot turn a workflow on). Click **New repository variable**, type `PYPI_PUBLISH` as the name and `true` as the value, and click **Add variable**. +4. **Publish a release** as usual ([Create executable installers](executable_creation.md)). In the **Actions** tab, the workflow **Publish the Python package to PyPI** runs next to **Build Release Installers**. When both jobs are green, the package is at `https://pypi.org/project//`. The upload job shows the link too. + +### Try it on TestPyPI first (optional) + +[TestPyPI](https://test.pypi.org) is a separate copy of PyPI for trials, with its own account. Add the same pending publisher at [test.pypi.org/manage/account/publishing](https://test.pypi.org/manage/account/publishing/), give the variable `PYPI_PUBLISH` the value `testpypi`, and publish a release. Install the result with: + +```bash +pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ +``` + +Then change the variable to `true`: the next release goes to PyPI. + +### Turn it off + +Delete the variable `PYPI_PUBLISH` (**Settings** > **Secrets and variables** > **Actions** > **Variables**). The workflow stays in the repository and is skipped at each release (a grey icon in the **Actions** tab, not a failure). What was published stays on PyPI. + +### Good to know + +- **A version can be uploaded only once**, even after it was deleted from PyPI. The workflow checks this before it builds anything and stops with a clear message; to publish a fix, make a new release with a higher version. +- **The release writes its version into `setup.py`** (the "Update version" commit of the release workflow), so the file and PyPI agree. +- **To approve each upload by hand**, open **Settings** > **Environments** > **pypi** (GitHub creates it at the first run) and add **Required reviewers**. +- **A repository that already publishes to PyPI with a workflow of its own** does not get `publish_pypi.yml` from the template update, so nothing is uploaded twice. +- If the workflow fails, see [Troubleshooting](troubleshooting.md#publishing-to-pypi-fails). + +--- + +
+ +[← Previous](app_manifest.md)            +[🏠 Home](README.md)            +[Next →](keep_app_up_to_date.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/initialise_repository.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/initialise_repository.md new file mode 100644 index 0000000..ca5d5c2 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/initialise_repository.md @@ -0,0 +1,55 @@ +# Initialise your repository + +The repository initialiser, a web form, fills your repository with your app's name, version, description and images. It opens a pull request in your repository; you merge it to finish. + +## What you need + +- A repository created from the template: see [Create your repository](create_repository.md). +- A name for your app (for example `CellAnalyzer`). We recommend the name of your GitHub repository. It may contain letters, numbers, spaces, `_`, `-` and `.`, from 3 to 50 characters. +- A first version number in the form `MAJOR.MINOR.PATCH` (for example `0.0.1`). +- A GitHub personal access token (classic, it starts with `ghp_`) that can write to the repository: see [Generate a GitHub personal access token](personal_access_token.md). The form refuses a fine-grained token (`github_pat_...`). +- Recommended: a one-sentence summary of what your app does, its kind, and the software it also works in. They go into the description file for the App Centre ([Describe your app for the App Centre](app_manifest.md)). +- Optional: PNG images for the installer. See [Customise the installer images](installer_images.md). + +## Fill in the form + +1. Open the [repository initialiser](https://labconstrictor-form.streamlit.app/). If it shows a `Zzzz` message, click `Yes, get this app back up!` and wait. +2. In the **Initialise GitHub repository** section, click **Start initialisation**. +3. Fill in **Project name** and **Initial project version**. Tick **Disable automatic code hiding in notebooks** only if users must edit your notebooks' code (see [Hide code cells in notebooks](code_hiding.md)). +4. Under **Describe your app (recommended)**, write the summary, choose the kind of app and the software it also works in. +5. Optionally upload the icon, welcome and header images. +6. Click **Validate submission**. If something is missing, the form lists what to fix. +7. Under **⬆️ Upload it to GitHub**, enter your repository's address (for example `https://github.com/your-lab/CellAnalyzer`) and your token, then click **🚀 Create pull request**. + +## Accept the pull request + +The form opens a pull request titled "Pull request for initialisation". Merge it: see [Accept a pull request](accept_pull_request.md). + +## Check that it worked + +After you merge the pull request: + +- Your repository's main page shows a new README titled with your app's name. +- These guides are listed in `.tools/docs/README.md`: the main README of the template moved there, and the new README links to it. +- `construct.yaml` shows your app's name and version instead of `PROJECT_NAME` and `VERSION_NUMBER`. + +## If something does not work + +- **The form says the token is fine-grained or not valid.** Create a classic token that starts with `ghp_` ([how](personal_access_token.md)). +- **The form says the repository address is not valid.** Use the form `https://github.com//`. +- **"Failed to push changes" or "Failed to create pull request".** Check that the token has the **repo** scope and belongs to an account that can write to the repository, and that the repository's default branch is `main`. +- **No pull request appears.** Look at the messages at the bottom of the form: they say which step failed. You can submit the form again. + +For other problems with your repository, see [Troubleshooting repository setup](troubleshooting.md). + + +--- + +
+ +[← Previous](create_repository.md)            +[🏠 Home](README.md)            +[Next →](accept_pull_request.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/install.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/install.md new file mode 100644 index 0000000..d0c84d5 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/install.md @@ -0,0 +1,63 @@ +# Install an app + +Download the installer for your system from the app's page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) (or from the app's GitHub release), then follow the steps for your system below. You install an app once; it can take several minutes. + +> **Check where it comes from.** The installers are not code-signed yet, so your system will warn you. Download only from the app's own GitHub release (the address starts with `https://github.com/` followed by the app's owner and repository, as shown on the app's page), and run it only if you trust that owner. A listing in the App Centre checks that the files come from the app's repository; it is not a security audit. + +## Before you start + +- **Internet connection.** The installer downloads the app's Python packages while it installs. +- **Install path.** The install path must contain no space: the installer refuses a path with a space. Use a path such as `C:\LabConstrictor\` on Windows or `~/labconstrictor/` on macOS and Linux. + +## Install on Windows + +1. Download the `.exe` file and double-click it. +2. If Windows shows "Windows protected your PC", click "More info" and then "Run anyway". The installers are not code-signed yet. + + ![Windows protected your PC: click More info, then Run anyway](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Windows_Protected_your_PC.png) + +3. Follow the on-screen prompts. A command prompt window opens during the installation: this is normal, do not close it. +4. Launch the app from the Start Menu or your desktop. + +## Install on a Mac + +1. Choose your file: open the Apple menu, then About This Mac. If the Chip or Processor says Intel, download the Intel installer; if it says M1, M2 or similar, download the Apple Silicon one. +2. Double-click the `.pkg` file. If macOS refuses to open it, go to System Settings, Privacy & Security, scroll down to the message about the package and click "Open Anyway". The button appears only after you have tried to open the file once. +3. Follow the prompts (we recommend "Install only for me"). Launch the app from your Applications folder. + +## Install on Linux + +1. Download the `.sh` file. +2. Open a terminal in the download folder and run `bash` followed by the name of the file you downloaded, for example: `bash MyApp-0.1.0-Linux-x86_64.sh` +3. Follow the prompts, then launch the app from your applications menu. + +## Check that it worked + +Open the app. A terminal window opens, then JupyterLab opens in your web browser with the app's Welcome notebook. What to do next: [Use notebooks after installation](notebook_usage.md). + +## If something does not work + +- The installer writes what it did to `menuinst_debug.log` in the install folder. +- See [Troubleshooting an installed app](troubleshooting_installed_app.md), or start from [Find your problem](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/help/). + +## Update an installed app + +- **macOS and Windows.** On macOS and Windows, update an app by [uninstalling the old version](#uninstall-an-app) first and then installing the new one: the installer does not install over an existing install. On macOS, if you already ran the new installer over the old version and it stopped or reported a failure at the end, move only the old app shortcut (for example `~/Applications/MyApp.app`) to the Bin, keep the app's folder in your home folder, and run the installer again. +- **Linux.** On Linux, running the installer with `-u` updates in place only if the previous install finished; otherwise delete `/pkgs` or uninstall the app and install it again. + +## Uninstall an app + +Uninstalling deletes the app's install folder and everything in it: move anything you saved there to another folder first. + +- **Windows.** Open Settings > Apps > Installed apps, find the app, click the three dots next to it and choose Uninstall. You can also double-click `Uninstall-.exe` in the app's install folder. If the app is still listed afterwards, see [Troubleshooting an installed app](troubleshooting_installed_app.md). +- **macOS and Linux.** Open a terminal and run the `uninstall.sh` script of the app's install folder (the folder you chose when you installed it), for example `bash ~/labconstrictor/MyApp/uninstall.sh`. It removes the app's shortcut (from the Applications folder of your home folder on macOS, from your applications menu on Linux), takes the app out of the tools list of napari, Fiji and QuPath, and deletes the install folder. + +## Where the app is listed + +If the app ships tools for napari, Fiji or QuPath, the installer registers them with LabConstrictor Tools, with the `hosts:` line of the app's `labconstrictor-app.yaml`. A program lists the app only if that line names it: with `hosts: [notebook, napari]` the app is listed in napari, and not in Fiji or QuPath. Without a `hosts:` line, every program lists the app, and `menuinst_debug.log` in the install folder says so (`'' declares no hosts, so it is listed in every host; ...`). + +To run the tools, install the plugin for your image software once: see [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). + +## Next + +Open the app and start working: [Use notebooks after installation](notebook_usage.md). diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/installer_images.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/installer_images.md new file mode 100644 index 0000000..ef2930a --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/installer_images.md @@ -0,0 +1,45 @@ +# Customise the installer images + +You can brand the installer and the app's shortcut with your own images. This is optional. Upload them when you [initialise your repository](initialise_repository.md); the form resizes them to the sizes below. + +You can provide these images: + +| Image | Recommended size | Format | Where it appears | +|------------|------------------|--------|-------------| +| Logo | 256x256 pixels | PNG | The installer and the app's shortcut. | +| Banner | 164x314 pixels | PNG | The vertical banner of the installer. | +| Header | 150x57 pixels | PNG | The header of the installer. | + +Images in the recommended size display best. Here are the images of the LabConstrictor installer as examples: + +## Logo +![LabConstrictor Logo](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/LabConstrictor_Logo.png) + +## Banner +![LabConstrictor Banner](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/LabConstrictor_Banner.png) + +## Header +![LabConstrictor Header](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/LabConstrictor_Header.png) + +## Default installer + +Without your own images, the installer uses default images: + +![Default Installer Images](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Customisation_Default.png) + +## Customised installer + +With your own images: + +![Customised Installer Images](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Customisation_Custom.png) + +--- + +
+ +[← Previous](executable_creation.md)            +[🏠 Home](README.md)            +[Next →](app_manifest.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_requirements.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_requirements.md new file mode 100644 index 0000000..c686776 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_requirements.md @@ -0,0 +1,115 @@ +# Generate the requirements of your notebook + +Every notebook you upload needs a `requirements.yaml` file: the Python version and the packages it uses, each with its exact version. The installer installs these packages on your users' computers. + +There are two ways to make the file: + +* **Option 1 (automated):** the Requirements Generator notebook reads the packages from the Python environment where your notebook runs. Use it when you start from scratch. +* **Option 2 (manual):** you write the file yourself and check it with the Requirements Validator notebook. Faster if you already have a `requirements.txt` with versions. + +## What you need + +- Your notebook, running without errors in a Python environment: on your computer (conda or virtualenv) or in Google Colab. +- For Option 1 on your computer: that same environment, with Jupyter. The generator must run in the environment your notebook uses, because it reads the package versions from it. + +## Option 1: Automated extraction of requirements + +### 1. Open the Requirements Generator notebook + +Open it where your notebook runs: + +* **On your computer:** download [Requirements_Generator.ipynb](../notebooks/Requirements_Generator.ipynb) (with the download button shown below) and open it in the environment you use for your notebook. If you have several conda environments, use the one your notebook runs in. + + ![Download Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Download_Notebook.png) + +* **Google Colab:** open the [Requirements Generator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Generator.ipynb). Colab runs each notebook in its own session, so the packages your notebook installs must be installed in the generator's session too: the generator finds your notebook's `pip install` commands and offers a cell that runs them. + +### 2. Run the Requirements Generator + +Run its cells in order and follow the instructions in the notebook: choose your notebook, add helper files your notebook uses if any, then generate the file. It saves `_requirements.yaml` next to the generator (in Colab it is also downloaded). You can upload it with that name: the upload form saves it as `requirements.yaml`. + +## Option 2: Manual extraction of requirements + +### 1. Create a `requirements.yaml` file + +Start from the [example requirements.yaml file](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/templates/requirements.yaml). It has three fields: + +* **`dependencies`:** every package the notebook uses, one per line, each starting with `- ` and fixed to one version with `==` (`pandas==2.2.2`). Optional extras are allowed (`colabfold[alphafold,openmm]==1.6.3`). The upload form refuses ranges such as `pandas>=2`. +* **`python_version`:** the Python version the notebook runs with (for example `3.11.1`). All notebooks of an app must use the same one. +* **`description`:** one sentence on what the notebook does. + +```yaml +dependencies: + - pandas==2.2.2 + - ipython==7.34.0 + - tqdm==4.67.1 +description: This notebook is for analyzing cell migration data... +python_version: 3.11.1 +``` + +### 2. Check it with the Requirements Validator notebook + +* **Google Colab (recommended, nothing to install):** open the [Requirements Validator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Validator.ipynb). +* **On your computer:** download [Requirements_Validator.ipynb](https://raw.githubusercontent.com/CellMigrationLab/LabConstrictor/main/.tools/notebooks/Requirements_Validator.ipynb) and open it in any Python environment that has `ipywidgets`. + +Follow the instructions in the notebook and give it your `requirements.yaml` when it asks. + +## Check that it worked + +- You have a `requirements.yaml` (or `_requirements.yaml`) file. +- Every line under `dependencies` has the form `package==version`, and `python_version` is the version your notebook runs with. + +You are ready to [upload your notebook](notebook_upload.md). + +## If something does not work + +- **A package is missing from the generated file.** The generator finds only packages installed in the environment it runs in. Open it in the environment of your notebook, or add the package by hand with its version. +- **The upload form says "Dependency '...' is not in the correct format".** Fix that line to `package==version`. +- **The workflow stops after the upload with conflicting versions.** Two notebooks ask for different versions of a package: see [When notebooks ask for different versions of a package](#when-notebooks-ask-for-different-versions-of-a-package). + +## What happens after you upload: the lock file + +When a notebook and its `requirements.yaml` reach the repository, the workflow **Updates on notebook change** merges the requirements of every notebook into `requirements.txt`, plus `requirements_gpu.txt` and, if a notebook needs them, `requirements-windows.txt`, `requirements-linux.txt` or `requirements-macos.txt`. + +The installer uses `requirements_gpu.txt` when it finds an NVIDIA GPU on Windows or Linux. In that file `tensorflow` becomes `tensorflow[and-cuda]` on Linux only: TensorFlow has had no Windows GPU build since version 2.10, and its CUDA packages exist only for Linux, so Windows keeps plain `tensorflow` (CPU). + +The workflow then writes a **lock file** next to each requirements file (`requirements.lock.txt`, ...). A lock file lists every package the installer installs, including the packages your packages depend on, each with its exact version, for Windows, macOS and Linux. The installer installs the lock file, so every installation of a release gets the same versions. + +* A lock file changes only when its requirements file, the Python version or the JupyterLab version changes. Pushing a notebook without new requirements does not move any version. +* To move every package to its newest version, delete the `requirements*.lock.txt` files and run the workflow by hand (**Actions > Updates on notebook change > Run workflow**). +* If the requirements cannot be locked, the workflow shows a warning and the installer installs the plain `requirements.txt` instead. + +### When notebooks ask for different versions of a package + +The merge never changes a notebook's requirement silently. Requirements are kept as written (`numpy>=1.24` stays `numpy>=1.24`), and the requirements of several notebooks are combined (`numpy>=1.24,<2`). The workflow stops, and no requirements file is written, when: + +* two notebooks pin a package to different versions (`numpy==1.26.4` and `numpy==2.0.0`); +* a pin does not meet another notebook's requirement (`numpy==2.0.0` and `numpy<2`); +* no version meets all the requirements (`numpy<2` and `numpy>=2.1`). + +The log of the **Run merge script** step names the package, every notebook and its requirement. Then either: + +* **make the notebooks agree:** change their `requirements.yaml` to a version that works for every notebook; or +* **decide explicitly** in `requirements_overrides.yaml`, at the top of the repository, which requirement every notebook gets, and why: + +```yaml +overrides: + numpy: + use: "==2.0.0" + reason: "Notebook A was re-run with numpy 2.0.0 and gives the same results; notebook B needs 2.0." +``` + +The decision and its reason are written at the top of the generated requirements files. Pushing `requirements_overrides.yaml` runs the workflow again. A release also stops while a conflict is not resolved. + +Requirements with different platform markers (`; sys_platform == "win32"`) are kept as separate lines, and `NumPy`, `numpy` and `num_py` count as the same package, as for pip. + +--- + +
+ +[← Previous](accept_pull_request.md)            +[🏠 Home](README.md)            +[Next →](notebook_upload.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_upload.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_upload.md new file mode 100644 index 0000000..e0fc1c7 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_upload.md @@ -0,0 +1,193 @@ +# Add or update a notebook + +Upload a notebook and its `requirements.yaml` to your repository with the LabConstrictor web form. The form opens a pull request; when you merge it, GitHub checks that the notebook's packages can be installed together. + +## What you need + +- An initialised repository: see [Initialise your repository](initialise_repository.md). +- Your notebook (`.ipynb`) and its requirements file: see [Generate the requirements of your notebook](notebook_requirements.md). +- A GitHub personal access token (classic, it starts with `ghp_`): see [Generate a GitHub personal access token](personal_access_token.md). + +## 1. Prepare your notebook + +The first cell of every notebook checks its version, so users see when a newer version exists. + +1. Add a code cell at the top of your notebook (see this [JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md) if you need help), and paste the code below into it. +2. Set `current_version` to the version of your notebook (for example `"0.0.2"`) and `notebook_name` to the name of the notebook file without `.ipynb`. + +> Each time you change what the notebook does, increase `current_version` so users can see there is a new version. + +```python +# @markdown Run this cell to check this notebook's version. + +current_version = "0.0.1" +notebook_name = "Notebook_template" # Replace with the actual notebook name + +# First of all check if ipywidgets is installed, if not through an informative error +try: + import ipywidgets as widgets +except ImportError: + raise ImportError("ipywidgets is not installed. Please install it using 'pip install ipywidgets' or 'conda install -c conda-forge ipywidgets'.") + +from IPython.display import display + +try: + from google.colab import output + output.enable_custom_widget_manager() + + try: + import yaml + except ImportError: + raise ImportError("pyyaml is not installed. Please install it using 'pip install pyyaml' or 'conda install -c conda-forge pyyaml'.") + + import requests + import base64 + + # Create widgets + github_repo = widgets.Text( + value="", + description="*GitHub Repository URL:", + placeholder="e.g https://github.com/username/repository", + layout=widgets.Layout(width="70%"), + style={'description_width': '150px'}, + ) + + github_token = widgets.Password( + value="", + description="*Personal Access Token:", + placeholder="[Disabled] e.g. ghp_XXXXXXXXXXXXXXXXXXXX", + disabled=True, + layout=widgets.Layout(width="70%"), + style={'description_width': '150px'}, + ) + + test_button = widgets.Button( + description="Test Connection", + button_style='success', + ) + + output_area = widgets.HTML() + + # By default the repository is considered public + if "repository_is_private" not in globals(): + repository_is_private = False + elif repository_is_private: + github_token.disabled = False + github_token.placeholder = "e.g. ghp_XXXXXXXXXXXXXXXXXXXX" + + def on_test_button_clicked(b): + global repository_is_private + + # Check that the GitHub repository URL is provided + if not github_repo.value: + output_area.value = "⚠️ Please provide a GitHub repository URL." + return + + # Get the owner and repo name from the URL + repo_url = github_repo.value.rstrip('/') + github_owner, github_repo_name = repo_url.split('/')[-2:] + + # Online version checking file path + version_file_path = "notebooks/notebook_latest_versions.yaml" + version_url = f"https://api.github.com/repos/{github_owner}/{github_repo_name}/contents/{version_file_path}" + + # Do an initial request to check if the repository is public + if not repository_is_private: + version_response = requests.get(version_url) + if version_response.status_code == 404: + repository_is_private = True + github_token.disabled = False + github_token.placeholder = "e.g. ghp_XXXXXXXXXXXXXXXXXXXX" + output_area.value = f"⚠️ We have detected that the repository might be private. Please provide a Personal Access Token and click 'Test Connection' again." + return + else: + headers = {"Accept": "application/vnd.github.v3+json"} + if not github_token.value: + output_area.value = "⚠️ Personal Access Token is required for private repositories." + return + headers["Authorization"] = f"token {github_token.value}" + + version_response = requests.get(version_url, headers=headers) + + # Check the response status + if version_response.status_code == 200: + content = version_response.json()['content'] + decoded_content = base64.b64decode(content).decode('utf-8') + config = yaml.safe_load(decoded_content) + # notebook_latest_versions.yaml groups the notebooks by folder: {"": {"": ""}} + latest_version = next((str(group[notebook_name]) for group in (config or {}).values() + if isinstance(group, dict) and notebook_name in group), "") + + output_area.value = (f"Notebook version: `{current_version}`
" + f"Latest version available: `{latest_version}`
") + + if latest_version == "": + output_area.value += "⚠️ This notebook is not listed in the version file.
" + elif current_version == latest_version: + output_area.value += "✅ This notebook is up-to-date.
" + else: + output_area.value += f"⚠️ A new version of this notebook is available." + else: + output_area.value += "⚠️ Could not retrieve the version file.
" + + test_button.on_click(on_test_button_clicked) + # Widget layout + widget_box = widgets.VBox([github_repo, github_token, test_button, output_area]) + display(widget_box) +except ImportError: + display(widgets.HTML('To check the notebook version, please go to the Welcome notebook.')) +``` + + +## 2. Generate the requirements file + +Create the `requirements.yaml` file of your notebook: see [Generate the requirements of your notebook](notebook_requirements.md). + +## 3. Upload to the repository + +1. Open the [LabConstrictor form](https://labconstrictor-form.streamlit.app/). If it shows a `Zzzz` message, click `Yes, get this app back up!` and wait. +2. Click **Upload/Update notebook**. +3. Upload your notebook file (`.ipynb`) and its requirements file. +4. Click **➕ Validate & Add Submission**. If the notebook and its requirements pass the checks, the notebook appears in the **📃 Submission list**. Repeat steps 3 and 4 to add more notebooks to the same pull request. +5. Under **⬆️ Upload it to GitHub**, enter your repository's address and your personal access token. +6. Click **🚀 Create pull request**. + +## 4. Merge the pull request + +The form opens a pull request titled "Upload/Update notebook" followed by the notebook's name. Merge it: see [Accept a pull request](accept_pull_request.md). The merge starts the workflow **Updates on notebook change**, which merges the requirements of all notebooks, hides the code cells (unless you disabled it) and checks that the packages can be installed. + +## Check that it worked + +- In the **Actions** tab, the run of **Updates on notebook change** has a green tick ([how to read a run](workflow_status.md)). +- Your notebook is in `notebooks//`, next to its `requirements.yaml`. +- `notebooks/notebook_latest_versions.yaml` lists the notebook with its `current_version`. + +You can now [create the installers](executable_creation.md). + +## If something does not work + +- **The form refuses the requirements file.** The message names the line to fix. Each dependency must be `package==version`: see [Generate the requirements of your notebook](notebook_requirements.md). +- **The workflow failed and your merge was undone.** When the merged requirements cannot be installed, the workflow reverts your merge automatically. Open the failed run, find the package that failed in the log, fix the notebook's requirements and upload again. +- **The workflow stops with conflicting versions.** Notebooks ask for different versions of the same package; nothing is installed and the requirements files are not changed. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package). +- **The version check says "This notebook is not listed in the version file".** `notebook_name` in the first cell does not match the notebook's file name. + +--- + +## How to update an existing notebook + +Updating a notebook works the same way as adding one: + +1. In the first cell of your notebook, increase `current_version` (for example from `1.0.0` to `1.0.1`). +2. If the notebook now uses other packages or versions, generate its requirements file again. +3. Upload the notebook and its requirements file with the [LabConstrictor form](https://labconstrictor-form.streamlit.app/), as above. Keep the notebook's file name exactly the same: a notebook with the same name replaces the old one. + +--- + +
+ +[← Previous](notebook_requirements.md)            +[🏠 Home](README.md)            +[Next →](executable_creation.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_usage.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_usage.md new file mode 100644 index 0000000..209dce7 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/notebook_usage.md @@ -0,0 +1,51 @@ +# Use notebooks after installation + +How to open an installed app, run its notebooks and update them. + +## Open the app + +To open the application, go to the Start Menu (Windows), the Applications folder (macOS) or your applications menu (Linux). Search for the application name and click its icon to start it. + +A terminal window opens first. It keeps JupyterLab running: leave it open while you work. After a few seconds, JupyterLab opens in your web browser with the Welcome notebook: + +![Welcome Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Welcome_Notebook.png) + +## Open a notebook + +Run the cell of the Welcome notebook. It shows a table of the app's notebooks, with their version and whether a newer version exists. Click **Open the notebook** in the last column to open a notebook in a new tab. + +If the app's repository on GitHub is private, the Welcome notebook asks for a GitHub personal access token to check for new versions: see [Generate a GitHub personal access token](personal_access_token.md). + +## Run a notebook + +Notebooks made with LabConstrictor can hide their code. Run each cell with its play button, or select the cell and click the play button in the top toolbar. The **Show/Hide Code** button in the toolbar shows the code. See [Hide code cells in notebooks](code_hiding.md) for pictures. If you are new to JupyterLab, see [this JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md). + +## Update a notebook + +When a newer version of a notebook is published, the Welcome notebook shows **Update** next to it. + +1. Close the notebook's tab first. Otherwise JupyterLab can save the old copy over the new one. +2. Click **Update**, then confirm with **Back up and update**. + +Your current copy, with your changes and outputs, is kept as `.backup-.ipynb` in the same folder. If the download fails, your notebook is not changed. + +## Close the app + +Keep the terminal window open until you have finished working with your notebooks. When you have, stop the Jupyter Lab session with **File > Shut Down** in Jupyter Lab (or click on the terminal window and press `Ctrl+C`). The terminal then asks you to press `Enter`, and closes. + +## If something does not work + +See [Troubleshooting an installed app](troubleshooting_installed_app.md). + + +--- + + +
+ +[← Previous](download_executable.md)            +[🏠 Home](README.md)            +Next → + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/template_synchronization.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/template_synchronization.md new file mode 100644 index 0000000..d9c0d42 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/template_synchronization.md @@ -0,0 +1,86 @@ +# Enable automatic LabConstrictor template updates + +The **Sync with Template Repository** workflow checks the LabConstrictor template every week. When a newer template version exists, it opens a pull request in your repository with the changes, for you to review and merge. + +To open that pull request, the workflow needs a token that you create once and save in your repository. The token gives access only to the repository you select, not to your other repositories. + +## What you need + +- Admin access to your app's repository on GitHub (to add a secret). + +## Step 1: Create the synchronization token + +![GIF showing the token creation](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Synchronisation_Token_Creation.gif) + +Open [this link](https://github.com/settings/personal-access-tokens/new?name=LabConstrictor+Sync&description=Allows+LabConstrictor+to+prepare+template+update+pull+requests.&expires_in=365&contents=write&pull_requests=write&workflows=write), which fills in most of the form, then: + +1. Under **Resource owner**, select the owner of your repository. +2. Under **Repository access**, select **Only select repositories**, then select your repository. +3. Choose an expiration period. The link suggests 365 days. +4. Check these repository permissions: + - **Contents:** Read and write + - **Pull requests:** Read and write + - **Workflows:** Read and write +5. Select **Generate token**. +6. Copy the token. + +> GitHub shows the token only once. Keep the page open until you have saved it in Step 2. + +## Step 2: Save the token as a repository secret + +![GIF showing the secret creation](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Synchronisation_Secret_Creation.gif) + +1. Open your repository. +2. Select **Settings**. +3. In the left sidebar, select **Secrets and variables**, then **Actions**. +4. Select **New repository secret**. +5. Enter this exact name: + + ```text + LABCONSTRICTOR_SYNC_TOKEN + ``` + +6. Paste the token into the **Secret** field. +7. Select **Add secret**. + +GitHub encrypts repository secrets: the token is not shown in the repository or in the workflow logs. + +## Check that it worked + +Open the **Actions** tab, select **Sync with Template Repository** and click **Run workflow**. The run ends with a green tick. If a newer template version exists, a pull request titled "Sync template to version ..." appears in the **Pull requests** tab: merge it as described in [Accept a pull request](accept_pull_request.md). + +## Repositories created before template version 0.1.12 + +The older synchronization workflow does not use `LABCONSTRICTOR_SYNC_TOKEN`. If a run failed with an error saying that a GitHub App cannot create or update a workflow without `workflows` permission, edit the workflow once: + +1. Open [`.github/workflows/sync_template.yml`](../../.github/workflows/sync_template.yml) in your repository. +2. Select the pencil icon to edit the file. +3. Replace all its lines with those of the [template's workflow](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.github/workflows/sync_template.yml). +4. Select **Commit changes** and commit directly to the default branch. +5. Run **Sync with Template Repository** again. + +The next template update then keeps the workflow up to date by itself. + +## Renewing an expired token + +When the token expires, runs fail with an authentication error such as "Bad credentials". Then: + +1. Create a new token as in Step 1. +2. Open **Settings → Secrets and variables → Actions**. +3. Select `LABCONSTRICTOR_SYNC_TOKEN`. +4. Select **Update secret** and paste the new token. +5. Run **Sync with Template Repository** again. + +## If something does not work + +See [Synchronisation is failing on GitHub Actions](troubleshooting.md#synchronisation-is-failing-on-github-actions). + +--- + +
+ +[← Previous](keep_app_up_to_date.md)            +[🏠 Home](README.md)            +[Next →](notebook_portability.md) + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/tools_bridge.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/tools_bridge.md new file mode 100644 index 0000000..f96331e --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/tools_bridge.md @@ -0,0 +1,78 @@ +# Expose your app's tools to napari, Fiji and QuPath (optional) + +Turn functions of your app's Python package into **tools** that people run in napari, Fiji and QuPath, and from the command line. Each tool gets a form made from its function signature. You declare the tools in your repository; the installer registers them on the user's computer. Apps that declare no tools are not affected. + +To expose your app's tools: + +1. Put your Python code in `src/` (see [Upload external code](external_code_upload.md)). +2. Declare the tools in a `_lc_tools` module, as shown below. +3. Name the programs your tools work in under `hosts:` in `labconstrictor-app.yaml`. +4. Test the tools, then publish a release. + +How to write a tool, with its inputs, outputs, form layout and tests, is in [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/). What the people who install your app do to run the tools is in [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). + +## What you need + +- An app repository made from this template, with your Python package in `src//`. +- Python functions with type annotations that you want to offer as tools. + +## Declare your tools + +1. Add a module named `_lc_tools` next to your package under `src/` (so `src/mytool_lc_tools/__init__.py` for + the package `mytool`). The installer registers tools only from a module with exactly this name. Declare tools in it with typed + functions, and import your science code **inside** the functions: + + ```python + from typing import Annotated + from labconstrictor_tools import Image, ImageOut, Min, tool + + @tool("Gaussian blur") + def blur(image: Image, sigma: Annotated[float, Min(0)] = 2.0) -> ImageOut: + from mytool.filters import gaussian + return gaussian(image, sigma) + ``` + + Keep the module light: it is imported to read the tool list, so heavy imports at the top slow every start. +2. If you can, import `labconstrictor_tools` only in `_lc_tools`, or inside functions. The rest of your package then also + works where LabConstrictor Tools is not installed: a notebook on Google Colab, a copy of the package used elsewhere, or an installation + where Tools failed to install. +3. Name the programs your tools work in under `hosts:` in `labconstrictor-app.yaml`: see [Describe your app for the App Centre](app_manifest.md). + napari, Fiji and QuPath list your app only if `hosts:` names them. +4. Test your tools with `labconstrictor-tools check` and `labconstrictor-tools test`, as + [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/) shows. + +## What the installer does + +When someone installs your app, the installer: + +1. installs your package; +2. if your package has a `_lc_tools` module, installs LabConstrictor Tools; +3. checks that your package can be imported; +4. registers the app (`labconstrictor-tools register ...`) with the version from the `version:` line of `construct.yaml` and the hosts of + `labconstrictor-app.yaml`. + +When the app is uninstalled, it is unregistered. + +If step 2 or 4 fails, the installer writes a `WARNING` to `menuinst_debug.log` in the install folder, skips the registration and finishes +the installation. The exception is a package that imports `labconstrictor_tools` at the top: then the import check of step 3 fails. + +The installer installs one fixed release of LabConstrictor Tools: the tag in `LC_TOOLS_PIN` of +[app/bash_bat_scripts/post_install.sh](../../app/bash_bat_scripts/post_install.sh) and +[app/bash_bat_scripts/post_install.bat](../../app/bash_bat_scripts/post_install.bat). Template updates move it. To install Tools from +another source (a wheel, a git URL or a mirror), set the environment variable `LC_TOOLS_SPEC` when the installer runs; it replaces the pin. +How Tools releases are made and pinned is in +[Operations](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/tools-operations/#pinning-tools-in-app-installers). + +## Check that it worked + +After you install a release of your app: + +- `menuinst_debug.log` in the install folder says `Tools registered`. +- `labconstrictor-tools list` shows your app and its tools. +- Your app appears in the programs you named under `hosts:`, once their plugin is installed. + +## If something does not work + +- `menuinst_debug.log` in the app's install folder says what the installer did with your tools. +- `labconstrictor-tools doctor` checks the Tools installation, and `labconstrictor-tools logs` shows its log. +- Other problems and their fixes: [Operations](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/tools-operations/). diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/troubleshooting.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/troubleshooting.md new file mode 100644 index 0000000..5f68a97 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/troubleshooting.md @@ -0,0 +1,75 @@ +# Troubleshooting repository setup + +Problems with your repository on GitHub. For problems with an installed app on your computer, see [Troubleshooting an installed app](troubleshooting_installed_app.md). + +## Synchronisation is failing on GitHub Actions + +The **Sync with Template Repository** workflow needs the repository secret `LABCONSTRICTOR_SYNC_TOKEN`, because template updates can change files in `.github/workflows/`. The setup is in [Enable automatic LabConstrictor template updates](template_synchronization.md). + +### "Synchronization setup required": the token is missing + +Create the token and save it under **Settings → Secrets and variables → Actions** with this exact name: + +```text +LABCONSTRICTOR_SYNC_TOKEN +``` + +### GitHub refuses to update a workflow file + +If the error says GitHub refuses to create or update a workflow without `workflows` permission, check that the token has all of these repository permissions: + +- **Contents:** Read and write +- **Pull requests:** Read and write +- **Workflows:** Read and write + +Repositories created before template version `0.1.12` also need the one-time workflow edit described in the synchronization guide, so that the workflow uses the secret. + +### Bad credentials or authentication failed + +The token has expired or was revoked. Create a new token and update the `LABCONSTRICTOR_SYNC_TOKEN` secret: see [Renewing an expired token](template_synchronization.md#renewing-an-expired-token). + +## The release stops at "check_placeholders.py" + +Before it builds the installers, the release workflow checks that no template placeholder (`PROJECT_NAME`, `PYTHON_PROJ_NAME`, `UNDERSCORED_PROJECT_NAME`, ...) is left in a file the installer ships. An installer with one would fail on your users' computers (for example `No module named 'PYTHON_PROJ_NAME'` at the end of the installation). + +The log of the failed step lists each file and line. Replace the placeholder there with your app's value: `PYTHON_PROJ_NAME` is the Python package of the app (usually its folder in `src/`), `PROJECT_NAME` the app name. For `app/menuinst/Welcome.ipynb`, edit `.tools/templates/Welcome_template.ipynb` instead: the Welcome notebook is made from it at every release. Commit, then publish the release again. + +## The release stops at "Installers to build" + +The release reads `distribution.platforms` in `labconstrictor-app.yaml` to decide which installers to build. It stops when the file is not valid YAML, when `platforms` is not a list, or when it lists none of the systems the release can build: `windows-x86_64`, `linux-x86_64`, `macos-arm64` and `macos-x86_64`. The log of the step says which. Fix `labconstrictor-app.yaml` (see [Describe your app for the App Centre](app_manifest.md)), commit, then publish the release again. + +## "The notebooks ask for incompatible package versions" + +The **Run merge script** step of **Updates on notebook change**, or the `merge_requirements.py --check` step of a release, stops when notebooks pin a package to different versions, or ask for versions that no single version meets. Its log lists the package, each notebook and its requirement. Make the notebooks agree, or decide in `requirements_overrides.yaml` which requirement every notebook gets and why, then push it: the workflow runs again. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package). + +If a template update created `requirements_overrides.yaml` for you, its entries keep the versions your app installed until then (the newest of the pins). Check each one with every notebook that uses the package, and replace its reason with yours. + +## Publishing to PyPI fails + +The workflow **Publish the Python package to PyPI** (`publish_pypi.yml`) runs at a release only when the repository variable `PYPI_PUBLISH` is `true` or `testpypi` (see [Upload external code](external_code_upload.md#4-publish-the-code-on-pypi-optional)). Its first job checks and builds the package; its second job uploads it. The installers do not depend on it: a failure here leaves the release and its installers as they are. + +| What you see | What to do | +|---|---| +| Both jobs are grey (skipped) | The variable is missing or has another value. It must be a **variable** (Settings > Secrets and variables > Actions > **Variables**), not a secret, named `PYPI_PUBLISH`, with the value `true` or `testpypi` exactly. | +| `invalid-publisher: valid token, but no corresponding publisher` | The trusted publisher on pypi.org (or test.pypi.org for `testpypi`) does not match this workflow. Check the five fields: owner, repository, workflow `publish_pypi.yml`, environment `pypi`, and the project name. Then re-run the failed job (Actions > the run > **Re-run failed jobs**). | +| `... isn't allowed to upload to project ...` (403) | The name belongs to another PyPI project that this repository is not a publisher of. If it is yours, add the publisher in that project's **Publishing** page; if not, choose another `name=` in `setup.py` (and `distribution.pip`). | +| `PyPI already has ` (or `File already exists`) | That version was uploaded before; a version can be uploaded only once, even after it was deleted. Publish a new release with a higher version. | +| `There is no Python package in src/` | Add your code as a folder with an `__init__.py` in `src/` (see [Upload external code](external_code_upload.md)), or delete the variable `PYPI_PUBLISH`. | +| `... also publishes to PyPI` | Another workflow of the repository uploads to PyPI too. Keep one: delete the variable `PYPI_PUBLISH`, or delete the other workflow. | +| `distribution.pip of labconstrictor-app.yaml is ..., but setup.py names the package ...` | Make the two names the same. | +| `PyPI refuses a package whose dependency is a URL` | `setup.py` lists a dependency as `name @ git+https://...`. Publish that dependency on PyPI and name it with a version, or move the URL to `requirements.txt` (the installer still installs it; the PyPI package leaves it out). | +| `setup.py still has the template placeholder ...` | Replace the placeholder in `setup.py` (the log says which), commit, and publish a new release. | +| The upload job waits | The `pypi` environment has required reviewers (Settings > Environments > pypi): one of them approves the upload in the run. | + +After a fix, re-run the failed jobs of the run if nothing in the repository changed (a publisher fixed on pypi.org); otherwise publish a new release. + +--- + +
+ +[← Previous](workflow_status.md)            +[🏠 Home](README.md)            +[Next →](personal_access_token.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/troubleshooting_installed_app.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/troubleshooting_installed_app.md new file mode 100644 index 0000000..76cf272 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/troubleshooting_installed_app.md @@ -0,0 +1,69 @@ +# Troubleshooting an installed app + +Problems with an app on your computer, after you installed it. For problems with your repository on GitHub, see [Troubleshooting repository setup](troubleshooting.md). + +## Where to find the logs + +Two files in the app's install folder (the folder you chose when you installed it) record what happened: + +- `menuinst_debug.log`: what the installer did. +- `launcher_debug.log`: what happened when you opened the app. If the app cannot start, a message names this file. + +Send them along when you ask the app's developer for help. + +## App still appears in the Windows Installed apps list after uninstalling + +On Windows, after you uninstall the app from `Settings > Apps > Installed apps` as explained in [Uninstall an app](install.md#uninstall-an-app), the app can stay in the list and refuse to uninstall again, with a message like this: + +![Uninstall error message](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/troubleshooting/Not_Uninstall.png) + +Uninstall it from the Control Panel instead: + +1. Open the Control Panel. You can search for it in the Windows search bar. +2. Go to `Programs > Programs and Features`. +3. Find the app in the list, right-click it, and select `Uninstall`. +4. A message may say something like "An error occurred while trying to uninstall xxx. It might have already been uninstalled." Click `Yes`. + +The app is then removed from the list. + +## Windows asks for administrator rights for python.exe while uninstalling + +Uninstalling an app made with template 0.1.20 or earlier may show a User Account Control prompt: "Do you want to allow this app from an unknown publisher to make changes to your device? python.exe", with the program location `"\python.exe" -m conda.core.initialize ...`. + +1. Click **No**. The prompt is not needed. +2. The uninstaller then shows a "Failed to clean AutoRun" error with Abort, Retry and Ignore: click **Ignore**. + +The uninstall then finishes normally, and nothing outside the app folder is changed. **Yes** and **Retry** do not help: the same error comes back. + +Do not click **Abort**, even though it is the default button: it stops the uninstall halfway and leaves the app folder on disk. If that happened, run `Uninstall-.exe` in the app folder again. + +Installers built with template 0.1.21 or later do not have this problem ([details](migration_0_1_21.md)). + +## The notebook fails with "No module named ..." although the installation finished + +The first cell that imports the app fails with `ModuleNotFoundError: No module named ''`. This happens with apps made with template 0.1.23 or earlier when someone once ran `python -m ipykernel install --user` on the computer (common with Anaconda or pip setups). Jupyter then has a personal "python3" kernel, and the app's notebooks run in that other Python instead of the app's own. + +Install a release made with template 0.1.24 or later: it always uses the app's own Python. Until then, you can delete the personal kernel folder, but the other Jupyter installations on the computer that use it lose it too: + +- Linux: `~/.local/share/jupyter/kernels/python3` +- macOS: `~/Library/Jupyter/kernels/python3` +- Windows: `%APPDATA%\jupyter\kernels\python3` + +## My changes to a notebook are gone after an update + +The **Update** button of the Welcome notebook keeps your copy before it replaces a notebook: look for `.backup-.ipynb` in the same folder and open it in JupyterLab. Apps made with template 0.1.30 or earlier replace the notebook without keeping a copy. + +## JupyterLab does not start because Windows reports an ASN.1 certificate error + +A broken certificate in the Windows certificate store can stop JupyterLab from starting. The app's launcher works around it: it first uses the system's certificates and, if one of them cannot be read, falls back to a verified certificate bundle. Certificate checks are never switched off. `launcher_debug.log` says which one was used. + +If your organisation uses its own certificate authority, save its certificates as a PEM file and set one of these environment variables to the path of that file before you install or open the app: + +- `LABCONSTRICTOR_CA_BUNDLE`, for every LabConstrictor app; +- `_CA_BUNDLE`, for one app: the app's name in capitals, with spaces and punctuation replaced by `_` (for the app "My Project", `MY_PROJECT_CA_BUNDLE`). + +To test the launcher without opening JupyterLab, run this in a command prompt (replace `` and ``): + +```text +\python.exe \\launch_jupyter.py --self-test +``` diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/workflow_status.md b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/workflow_status.md new file mode 100644 index 0000000..7115b94 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/.tools/docs/workflow_status.md @@ -0,0 +1,34 @@ +# Check the status of GitHub workflows + +GitHub Actions runs workflows in your repository: when a notebook or its requirements change (**Updates on notebook change**), when the code in `src/` changes (**Updates on external code change**), when you publish a release (**Build Release Installers**) and every week for template updates (**Sync with Template Repository**, which needs the one-time [`LABCONSTRICTOR_SYNC_TOKEN` setup](template_synchronization.md)). + +## 1. Monitor the progress + +1. Go to the **Actions** tab of your repository. +2. Find the run that matches your latest change or release. +3. Check its status icon: + +![GitHub Actions Status Icons](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/actions_status_icons.png) + +## 2. How to debug a failure + +1. Click the failed run, then the red step: its log says what went wrong. +2. If the run has an **Artifacts** section at the bottom of its page, download the log file there (a plain `.log` text file, nothing to unzip). It holds the error, the workflow and the script that failed, with instructions at the top for an AI assistant: paste the whole file into one (such as ChatGPT, Gemini or Claude) and it explains the error and how to fix your notebook or `requirements.yaml`. + +For known errors, see [Troubleshooting repository setup](troubleshooting.md). + +### Best practice for large updates + +The workflows run only on your main branch, so a change is checked once it is merged. For a big update, such as several notebooks or new dependencies, upload one notebook at a time and wait for the green tick before the next: a failure then points to one change. + +--- + +
+ +← Previous            +[🏠 Home](README.md)            +[Next →](troubleshooting.md) + + +
+ diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/accept_pull_request.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/accept_pull_request.md new file mode 100644 index 0000000..c0fd3dd --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/accept_pull_request.md @@ -0,0 +1,35 @@ +# Accept a pull request + +Follow these steps or watch the GIF at the end to learn how to accept a Pull Request (PR) on GitHub. LabConstrictor template updates are delivered this way after you complete the [automatic synchronization setup](template_synchronization.md). + +## 1. Go to the Pull Requests tab + +Go to the **Pull Requests** tab in your GitHub repository to see a list of all Pull Requests. You can refer to the screenshot below. + +![Pull Request Tab](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/PR_tab.png) + +## 2. Select the Pull Request to review + +The most recent Pull Request is usually at the top. Click its title to open and review it. + +## 3. Merge the Pull Request + +Click the green **Merge pull request** button, then click **Confirm merge** to complete the process. + +## 4. Delete the branch (optional) + +Once you have merged, you can delete the related branch by clicking the **Delete branch** button. + +![Accept a Pull Request GIF](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Accept_PR.gif) + + +--- + +
+ +[← Previous](initialise_repository.md)            +[🏠 Home](README.md)            +[Next →](notebook_requirements.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/app_manifest.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/app_manifest.md new file mode 100644 index 0000000..c5b787b --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/app_manifest.md @@ -0,0 +1,202 @@ +# Describe your app: the `labconstrictor-app.yaml` file + +`labconstrictor-app.yaml` is a small text file in the root of your repository. It says what your app is, in your own words. You write it once and keep it up to date yourself. + +Three things read it: + +- **The [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/)** builds your app's card and page from it. +- **Your release workflow** reads `platforms` to decide which installers to build. +- **Your installer** passes `hosts` and `host_requirements` to napari, Fiji and QuPath, so they know whether to list your app. + +Version numbers and download links are not in the file. They always come from your latest GitHub release. + +## Step 1: get the file + +The [repository initialiser](initialise_repository.md) asks for a one-sentence summary, the kind of app and the software it also works in. It adds the file to the initialisation pull request. Read it there and edit it if you like. + +If you skipped that section, or your repository is older than the file, create `labconstrictor-app.yaml` in the root of your repository and paste the minimal example below. The [Submit page](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/) also has a form that writes the file for you and checks it as you type. + +## Step 2: start with the minimal file + +These five fields are required. This file is complete and valid: + +```yaml +schema: 1 +name: My App +summary: Counts nuclei in 2D fluorescence images and saves a table. +kind: analysis +distribution: + installer: true +``` + +## Step 3: add what helps people choose your app + +A fuller example. Everything after `distribution` is optional. + +```yaml +# yaml-language-server: $schema=https://cellmigrationlab.github.io/LabConstrictor-Site/schema/labconstrictor-app.schema.json +schema: 1 +name: My App +summary: Counts nuclei in 2D fluorescence images and saves a table. +description: |- + A few paragraphs of plain text. + + Separate paragraphs with a blank line. +kind: analysis +hosts: [notebook, napari, qupath] +host_requirements: + napari: + min_version: 0.1.0-alpha.5 + why: Older plugins do not show the outlines + required: false +distribution: + installer: true + platforms: [windows-x86_64, macos-arm64, linux-x86_64] + colab: + - label: Notebook + url: https://colab.research.google.com/github/you/my-app/blob/main/notebooks/App/App.ipynb + pip: my-app +status: Available +license: MIT +authors: + - name: Ada Lovelace + orcid: 0000-0002-1825-0097 +doi: 10.1371/journal.pbio.3002740 +inputs: + - 2D TIFF images, one channel per file +outputs: + - Label masks and a CSV table +limitations: + - Not tested on 3D data +quickstart: + - Open the app and run the Welcome notebook. +categories: [nuclei, counting] +homepage: https://github.com/you/my-app +docs_url: https://github.com/you/my-app#readme +icon: app/logo/logo.png +screenshots: + - path: docs/screenshot.png + caption: The result table next to the segmented image +``` + +The first line lets editors with YAML support (for example VS Code) check the file as you type. Everything is plain text: no HTML and no Markdown. + +## The fields + +| Field | Required | What it does | Example | +|---|---|---|---| +| `schema` | Yes | The format version. Always `1`. | `1` | +| `name` | Yes | The name people know the app by (2 to 60 characters). | `My App` | +| `summary` | Yes | One sentence for the app card (20 to 200 characters). | `Counts nuclei in 2D images.` | +| `kind` | Yes | What the app is for. One of `analysis`, `segmentation`, `simulation`, `game`, `training`, `utility`. It drives the filter in the App Centre. | `analysis` | +| `distribution` | Yes | How people get the app. At least one of `installer`, `colab`, `pip`. See below. | `installer: true` | +| `hosts` | No | Where the app's tools run: `notebook`, `napari`, `fiji`, `qupath`. See below. | `[notebook, napari]` | +| `host_requirements` | No | The oldest napari, Fiji or QuPath plugin your tools need. See below. | | +| `description` | No | A few paragraphs for the app page (up to 2000 characters). | | +| `status` | No | `Experimental`, `Available` or `Deprecated`. | `Available` | +| `license` | No | The licence, as an SPDX name. | `MIT` | +| `authors` | No | A list of people: `name`, and optionally `orcid`. | `- name: Ada Lovelace` | +| `doi` | No | The DOI of the paper to cite, not of a software archive. The app page shows it as the citation. | `10.1371/journal.pbio.3002740` | +| `inputs`, `outputs`, `limitations` | No | Short lists for the app page: one to six lines of 5 to 200 characters each. | `- 2D TIFF images` | +| `quickstart` | No | Up to six short steps for a first run. | `- Open the app.` | +| `categories` | No | Up to six words a scientist would search for. | `[nuclei, counting]` | +| `homepage`, `docs_url` | No | Web addresses. They must start with `https://`. | | +| `icon` | No | A square PNG in your repository. SVG is not accepted. | `app/logo/logo.png` | +| `screenshots` | No | One to six pictures in your repository (PNG, JPG or GIF), each with a `path` and a `caption`. The caption is also the text for screen readers. | | + +The App Centre asks for a few optional fields: `status`, `quickstart`, `screenshots`, a licence, and `inputs` and `outputs` for analysis, segmentation and simulation apps. Without them your app is still listed; its page says "Not stated" or leaves that part out. + +### `distribution`: how people get the app + +| Key | What it does | +|---|---| +| `installer: true` | Your latest GitHub release carries the installers LabConstrictor builds. | +| `platforms` | The systems you support. Needs `installer: true`. Only these installers are built and offered. | +| `colab` | A list of Google Colab notebooks, each with a `label` and a `url` on `colab.research.google.com`. Only the notebooks you list are shown. | +| `pip` | The name of your package on PyPI. | + +`platforms` also decides which installers your releases build (template 0.1.24 or later). Leave a system out when your app cannot run there. Without `platforms`, every installer is built: `windows-x86_64`, `linux-x86_64`, `macos-arm64` (Apple silicon) and `macos-x86_64` (Intel Macs). `windows-arm64` and `linux-arm64` are accepted, but no installer is built for them. + +### `hosts`: where your tools are offered + +This field matters only if your app [exposes tools](tools_bridge.md). napari, Fiji and QuPath list your app only if you name them here. Write the hosts you have tested the app in. + +- `hosts: [notebook]` means no plugin lists the app. Its tools still work in the notebook and on the command line. +- Without a `hosts` line, every plugin lists the app. Say what you mean instead. +- Names are lower case. The check refuses a misspelt, repeated or capitalised name. + +## Plugin versions your tools need (optional) + +If your tools rely on a fix or a feature of the napari, Fiji or QuPath plugin that older plugins lack, say so with `host_requirements`. People with an older plugin keep seeing your app, with one sentence saying which plugin to update and where; your app page on the App Centre lists the versions under "Plugin versions". + +```yaml +host_requirements: + qupath: + min_version: 0.1.0-alpha.7 # a release tag of the plugin, with or without v + features: [shapes_owner_v1] # optional: a host feature id + why: Replace keeps your own annotations # optional: one line shown to the person + fiji: + min_version: 0.1.0-alpha.7 +``` + +- Name only `napari`, `fiji` or `qupath`: the notebook ships with your app and needs no plugin. +- Each needs `min_version`, `features`, or both. `required: true` makes an older plugin refuse your tools instead of warning; use it only when they really fail there. +- Write it as a block, as above. The installer passes this file to `labconstrictor-tools register`, which refuses a malformed block (a misspelt host or key, a version like `latest`); `labconstrictor-tools check --module _lc_tools --app-manifest labconstrictor-app.yaml` shows what it read. +- The feature ids and the rule are in the [LabConstrictor-Tools documentation](https://github.com/CellMigrationLab/LabConstrictor-Tools/blob/main/docs/PROTOCOL.md#host-requirements-which-plugin-an-app-needs). + +## The automatic check + +The **Check App Centre manifest** workflow runs when you change the file and when you publish a release: + +- If the file is missing, it shows a warning and passes. +- If the file is invalid, it fails and says what to fix. This never stops your installers from being built. +- It rejects fields it does not know (this catches typos, so the schema is not loosened); the template keeps its copy of the schema in step with the App Centre, see [Keep your app up to date](keep_app_up_to_date.md). +- It also checks that the icon and screenshots you name exist in the repository. + +## Check it yourself + +To get an answer before you push, you have two more ways: + +1. **On your computer.** From the root of your repository: + + ```bash + pip install pyyaml jsonschema + python .tools/python/check_app_manifest.py + ``` + +2. **In your browser.** Paste your values into the form on the [Submit page](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/). It checks them against the same schema. + +If your app exposes tools, also run `labconstrictor-tools check --module _lc_tools --app-manifest labconstrictor-app.yaml`. It prints the `hosts` and `host_requirements` it read, which is what the installer will register. + +The rules themselves are in the [schema](https://cellmigrationlab.github.io/LabConstrictor-Site/schema/labconstrictor-app.schema.json). Your repository has a copy in `.tools/schema/`, and the check uses that copy. + +## Common mistakes + +| What the check says, or what you see | Fix | +|---|---| +| A field "is not allowed" or is "unexpected" | The name is misspelt, or it is at the wrong level. For example `platforms` belongs under `distribution`. | +| `summary` is too short or too long | Write one sentence of 20 to 200 characters. | +| `platforms` without `installer` | Add `installer: true`. `platforms` only applies to installers. | +| The icon or a screenshot is "not found" | The path starts at the root of your repository, with no leading `/`. The file must be committed. | +| A Colab link is refused | The address must start with `https://colab.research.google.com/`. | +| `min_version: 0.2` is refused | YAML reads `0.2` as a number. Put it in quotes: `"0.2"`. | +| Your app is missing from napari, Fiji or QuPath | The host is not in `hosts`, or the app was installed before you added it. Publish a release and install it again. | +| The check passes but nothing changes in the App Centre | The App Centre reads the file from your default branch and updates once a day. | +| Text shows `**stars**` or tags | The fields are plain text. Remove Markdown and HTML. | + +## Get listed + +Having the file does not list your app by itself. To list it, [submit your repository](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/) to the App Centre. You do this once: later releases appear by themselves. + +The technical rules for `hosts` and `host_requirements` are in the [LabConstrictor-Tools manifest reference](https://cellmigrationlab.github.io/LabConstrictor-Tools/MANIFEST/). + +--- + +
+ +[← Previous](initialise_repository.md)            +[🏠 Home](README.md)            +[Next →](external_code_upload.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/before_getting_started.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/before_getting_started.md new file mode 100644 index 0000000..033d911 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/before_getting_started.md @@ -0,0 +1,52 @@ +# Before getting started with LabConstrictor + +Welcome to LabConstrictor! This guide will walk you through the basics and show you what you need to get started. + +## LabConstrictor in a nutshell + +LabConstrictor is a template repository that lets you turn Jupyter notebooks into desktop apps. It handles the setup for you via automated GitHub Actions. Here are its main features: + +### Easy configuration + +LabConstrictor has a web form that makes it easy to set up your repository, add your branding, and upload or update your notebooks and their dependencies. + +### Cross-platform installers + +Automatic workflows create installers for Windows (.exe), macOS (.pkg), and Linux (.sh). This makes it simple for users on any platform to install and run your notebooks. The installers are created using [Conda Constructor](https://github.com/conda/constructor). + +### Environment management + +LabConstrictor uses `requirements.yaml` files to manage dependencies. Automatic workflows ensure your notebooks run consistently across different systems. LabConstrictor also includes helper notebooks for generating and validating requirement files. + +### Version control + +LabConstrictor includes helper cells that track notebook versions and notify users when updates are available. This way, everyone can use the latest features and fixes. + +### User-friendly experience + +The installers take care of the setup, so users can open your notebooks with a desktop app. The app shows a Welcome Dashboard where users can check versions and pick notebooks. Notebooks have hidden code and a play button to run cells, giving a clean, app-like feel. Your repository can be private or public, giving you full control over who can access and use your notebooks. + +### Offline usage + +If your notebooks don’t need internet access, users can run the desktop apps offline after they install them. + +## LabConstrictor requirements + +To get started with LabConstrictor, you only need the following: + +- **🐙 GitHub Account:** You’ll need a GitHub account to make a new repository from the LabConstrictor template. +- **📒 Jupyter Notebooks:** Have your Jupyter notebooks ready to package into desktop apps. +- **🐍 Python Environment:** You’ll need a Python environment (local or online) where your notebooks run without errors. This is needed to create and check requirement files. Alternatively, you can create the requirement files yourself, but this may be prone to errors. +- **(Optional) 🖼️ Images, logo and icons:** for branding your executable installer. We recommend following the [images guidelines](./installer_images.md) for further information and guidance. + + +--- + +
+ +← Previous            +[🏠 Home](README.md)            +[Next →](create_repository.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/create_repository.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/create_repository.md new file mode 100644 index 0000000..0d30864 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/create_repository.md @@ -0,0 +1,45 @@ +# Create your repository + +To start, open the [LabConstrictor template on GitHub](https://github.com/CellMigrationLab/LabConstrictor) and click the `Use this template` button at the top of the page. This will let you create a new repository using the LabConstrictor template. + + +1. Click the green **Use this template** button at the top right of the main repository page. +2. Select **Create a new repository**. + +![Use template screenshot](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Use_Template.png) + +3. Next, you’ll need to fill in some details: + +* **Include all branches:** +Please, let the default `Off` option. + +* **Owner:** +Pick either your personal account or your research group’s organization. + +* **Repository Name:** +Pick a short, memorable name (for example, `MyLabTools`). +> **Note:** This name will be used as the default name for your application installer. + +* **Description** *(Optional)*: +Write a brief description of what your notebooks do (for example, "Automated cell migration analysis"). + +* **Visibility:** + * **Public:** Select this if you want to share your installer right away. + * **Private:** Select this if you’re still working on the tools or want to keep the code within your lab. A private repository cannot be listed in the App Centre: make it public before you submit your app. + +4. Click **Create repository**. 🎉 That’s it! Your repository is now set up and ready to go. + +## Template updates (optional, later) + +We recommend setting up automatic template updates after your first release. Without the update token, the weekly **Sync with Template Repository** run stops with the error "Synchronization setup required" as soon as a newer template version exists, and your repository receives no update pull request. See [Keep your app up to date](keep_app_up_to_date.md). + +--- + +
+ +[← Previous](before_getting_started.md)            +[🏠 Home](README.md)            +[Next →](initialise_repository.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/executable_creation.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/executable_creation.md new file mode 100644 index 0000000..008b322 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/executable_creation.md @@ -0,0 +1,41 @@ +# Create installer files + +After uploading your notebooks to the repository, follow these steps to create executable files for sharing. + +## Please check before proceeding + +Open the Actions tab in your repository and check that no workflows are running. If one is in progress, wait until it finishes. Starting a release while other jobs are running may cause build conflicts. + +## 1. Draft a new release + +1. Go to your repository's main page. +2. Click on Releases (usually on the right sidebar). +3. Click `Create a new release` and provide the following information: + - **Tag**: Click `Create a new tag` and enter a version number, for example, `0.0.1`. + > **IMPORTANT**: Make sure that it follows a semantic versioning format (MAJOR.MINOR.PATCH) e.g. `1.0.0`, `1.2.3`, `2.1.0`. A `v` in front (`v1.0.0`) also works: the installers are named with the version without it. + - **Release title**: Enter a title for your release, such as `Initial release`. + - **Description** (optional): Enter a description for your release, for example, `This is the initial release of my project.` + +## 2. Publish the release + +Once you have entered all the required information, click `Publish release`. This action will start the automated workflow to create installer executable files for your notebooks. To monitor the process, see [How to check the automatic workflow status](workflow_status.md). + +When the automated workflow completes, open your repository's **Releases** page, open the release you published and download the installers from its **Assets** list. + +## 3. After the release + +- Try your installer yourself: [Install an app](install.md), then [Use notebooks after installation](notebook_usage.md). +- List your app in the App Centre: [Describe your app for the App Centre](app_manifest.md). +- Receive future template improvements as pull requests: [Keep your app up to date](keep_app_up_to_date.md). + + +--- + +
+ +[← Previous](notebook_upload.md)            +[🏠 Home](README.md)            +[Next →](installer_images.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/external_code_upload.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/external_code_upload.md new file mode 100644 index 0000000..6a5f1c6 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/external_code_upload.md @@ -0,0 +1,125 @@ +# Upload external code + +If you want to use your own Python modules or scripts in Jupyter notebooks, follow these steps to upload them easily. + +## 1. Prepare your external code + +Organize your external code and follow Python packaging best practices. Set up the right folder structure, add an `__init__.py` file, and list any required dependencies. + +**Suggested Directory Structure:** + +```text +src/ +|-- PYTHON_PROJ_NAME/ +| |-- __init__.py +| |-- my_script.py +| |-- subpackage/ +| |-- __init__.py +``` + +### What goes in `__init__.py`? + +Think of `__init__.py` as the file that tells Python “this folder is a package”. + + If you leave it empty, that is perfectly fine—the package will still import correctly. When you want to make notebooks feel friendlier, you can re-export helper functions so users can discover them more easily: + +```python +# src/PYTHON_PROJ_NAME/__init__.py +from .my_script import run_analysis, load_config + +__all__ = ["run_analysis", "load_config"] +``` + +Each folder that you plan to import (for example, `src/subpackage/`) should also have its own `__init__.py`. Keep it empty unless you want to expose selected helpers from that subpackage. + +If you need further readings on `__init__.py`, check out this quick [Geeks for Geeks tutorial](https://www.geeksforgeeks.org/python/what-is-__init__-py-file-in-python/) or the [Real Python guide](https://realpython.com/python-init-py/). +## 2. Upload your external code to the repository + +Go to the src folder in your repository and upload your files or folders there. + +![Upload external code GIF](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Upload_src.gif) + +## 3. How to import into your notebook + +Once uploaded, your external code will be available to your notebooks as a package. To use it, import it as shown in the examples below: + +**Import the whole package:** +```python +import PYTHON_PROJ_NAME +``` + +If your folder under `src/` is called `celltools`, then `import celltools` will work because `src/celltools/__init__.py` exists. + +**Import function:** +```python +from PYTHON_PROJ_NAME import my_script +``` + +**Import submodule:** +```python +from PYTHON_PROJ_NAME.subpackage import submodule1 +``` + +## 4. Publish the code on PyPI (optional) + +The installer always puts your package into the app. You can also publish it on [PyPI](https://pypi.org), so that anyone can install it with `pip install`, in Google Colab or in their own Python. Each release then does both, with the same version: the GitHub Actions workflow `.github/workflows/publish_pypi.yml` builds the package and uploads it when you publish a release, next to the installers. + +It is **off until you turn it on**, and GitHub stores no password or token for it: PyPI trusts this repository's workflow directly ([trusted publishing](https://docs.pypi.org/trusted-publishers/)). + +**What is published** + +| | | +|---|---| +| Name | The `name=` of `setup.py`: the name of the package, given when the repository was initialised (unless you changed it). If `labconstrictor-app.yaml` has `distribution.pip`, it must be the same name. | +| Version | The release tag without the `v`: release `v1.2.0` publishes 1.2.0. | +| Code | Every package in `src/` (a folder with an `__init__.py`). | +| Dependencies | Each line of `requirements.txt`, as it is written (exact versions included). Options (`-r`, `--extra-index-url`), paths and URLs are left out, with a warning in the log: PyPI refuses dependencies given as URLs. | +| Description | `README.md` of the repository, shown on the PyPI page. | +| License | The `LICENSE` file. | + +### One-time setup + +1. **Check that the name is free.** Open `https://pypi.org/project//`. A "404 Not Found" page means nobody uses it. If it is taken, change `name=` in `setup.py` (and `distribution.pip`) and commit. +2. **Register this workflow on PyPI.** Log in to [pypi.org](https://pypi.org) (create an account if you have none; PyPI asks for two-factor authentication). Open your account menu > **Your projects** > **Publishing** ([pypi.org/manage/account/publishing](https://pypi.org/manage/account/publishing/)). Under **Add a new pending publisher**, choose the **GitHub** tab. The form has five fields; fill them in exactly: + - **PyPI Project Name:** the name of the package. + - **Owner:** the GitHub user or organisation that owns the repository (`CellMigrationLab` in `github.com/CellMigrationLab/MyApp`). + - **Repository name:** the repository (`MyApp`). + - **Workflow name:** `publish_pypi.yml` + - **Environment name:** `pypi` + + Click **Add**. The publisher appears under **Pending publishers** below the form. It does not reserve the name: the project is created by your first release. If the project already exists on PyPI and you own it, add the publisher in the project instead: **Your projects** > the project > **Manage** > **Publishing**. +3. **Turn it on in GitHub.** In the repository, open **Settings** > **Secrets and variables** > **Actions**, then the **Variables** tab (not **Secrets**: a secret cannot turn a workflow on). Click **New repository variable**, type `PYPI_PUBLISH` as the name and `true` as the value, and click **Add variable**. +4. **Publish a release** as usual ([Create executable installers](executable_creation.md)). In the **Actions** tab, the workflow **Publish the Python package to PyPI** runs next to **Build Release Installers**. When both jobs are green, the package is at `https://pypi.org/project//`. The upload job shows the link too. + +### Try it on TestPyPI first (optional) + +[TestPyPI](https://test.pypi.org) is a separate copy of PyPI for trials, with its own account. Add the same pending publisher at [test.pypi.org/manage/account/publishing](https://test.pypi.org/manage/account/publishing/), give the variable `PYPI_PUBLISH` the value `testpypi`, and publish a release. Install the result with: + +```bash +pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ +``` + +Then change the variable to `true`: the next release goes to PyPI. + +### Turn it off + +Delete the variable `PYPI_PUBLISH` (**Settings** > **Secrets and variables** > **Actions** > **Variables**). The workflow stays in the repository and is skipped at each release (a grey icon in the **Actions** tab, not a failure). What was published stays on PyPI. + +### Good to know + +- **A version can be uploaded only once**, even after it was deleted from PyPI. The workflow checks this before it builds anything and stops with a clear message; to publish a fix, make a new release with a higher version. +- **The release writes its version into `setup.py`** (the "Update version" commit of the release workflow), so the file and PyPI agree. +- **To approve each upload by hand**, open **Settings** > **Environments** > **pypi** (GitHub creates it at the first run) and add **Required reviewers**. +- **A repository that already publishes to PyPI with a workflow of its own** does not get `publish_pypi.yml` from the template update, so nothing is uploaded twice. See [the design note of template 0.1.25](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_25.md). +- If the workflow fails, see [Troubleshooting](troubleshooting.md#publishing-to-pypi-fails). + +--- + +
+ +[← Previous](app_manifest.md)            +[🏠 Home](README.md)            +[Next →](keep_app_up_to_date.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/initialise_repository.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/initialise_repository.md new file mode 100644 index 0000000..0b31be3 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/initialise_repository.md @@ -0,0 +1,22 @@ +# Initialise your repository + +Now that your repository is set up, you can start to customise it. To get started, you will need: + +- A name for your project/application (e.g., `CellAnalyzer`). +- An initial version number (e.g., `0.0.1`). +- A one-sentence summary of what your app does, its kind, and the software it also works in. They go into the description file for the [App Centre](app_manifest.md). +- (Optionally) Images for App installer customisation. See [Installer Images Customisation](installer_images.md) for more details on the images you can provide. + +Once you have everything ready, go to [https://labconstrictor-form.streamlit.app/](https://labconstrictor-form.streamlit.app/). If you see a `Zzzz` message for inactivity, click `Yes, get this app back up!`. Next, select `Start initialisation` in the **Initialise GitHub repository** section. Follow the instructions on the website. After you submit the form, a Pull Request with suggested changes will be created in your repository. To learn how to accept these suggestions, see [How to accept a Pull Request](accept_pull_request.md). After you accept the suggestions, the main README will move to [.tools/docs](.). But don't be afraid, the new README will have a link pointing the instructions for future reference, so you won’t lose access to them. + + +--- + +
+ +[← Previous](create_repository.md)            +[🏠 Home](README.md)            +[Next →](accept_pull_request.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/install.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/install.md new file mode 100644 index 0000000..e4fcc0b --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/install.md @@ -0,0 +1,54 @@ +# Install an app + +Installing takes about 6-8 minutes and you only do it once. You need an internet connection while installing: the installer downloads the app's Python packages. Download the installer for your system from the app's page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) (or from the app's GitHub release) and follow the steps for your system. + +> **Check where it comes from.** The installers are not code-signed yet, so your system will warn you. Download only from the app's own GitHub release (the address starts with `https://github.com/` followed by the app's owner and repository, as shown on the app's page), and run it only if you trust that owner. A listing in the App Centre checks that the files come from the app's repository; it is not a security audit. + +> A command prompt window opens during installation on Windows; this is normal, do not close it. + +## Before you install + +- **Install path.** The install path must contain no space: the installer refuses a path with a space. Use a path such as `C:\LabConstrictor\` on Windows or `~/labconstrictor/` on macOS and Linux. + +## Install on Windows + +1. Download the `.exe` file and double-click it. +2. If Windows shows "Windows protected your PC", click "More info" and then "Run anyway". The installers are not code-signed yet. + + ![Windows protected your PC: click More info, then Run anyway](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Windows_Protected_your_PC.png) + +3. Follow the on-screen prompts. Launch the app from the Start Menu or your desktop. + +## Install on a Mac + +1. Choose your file: open the Apple menu, then About This Mac. If the Chip or Processor says Intel, download the Intel installer; if it says M1, M2 or similar, download the Apple Silicon one. +2. Double-click the `.pkg` file. If macOS refuses to open it, go to System Settings, Privacy & Security, scroll down to the message about the package and click "Open Anyway" (it appears only after you tried to open the file once). If you do not see it, try opening the file again, then check this page again. +3. Follow the prompts (we recommend "Install only for me"). Launch the app from your Applications folder. + +## Install on Linux + +1. Download the `.sh` file. +2. Open a terminal in the download folder and run `bash` followed by the name of the file you downloaded, for example: `bash MyApp-0.1.0-Linux-x86_64.sh` +3. Follow the prompts, then launch the app from your applications menu. + +## Update an installed app + +- **macOS and Windows.** On macOS and Windows, update an app by [uninstalling the old version](#uninstall-an-app) first and then installing the new one: the installer does not install over an existing install. On macOS, if you already ran the new installer over the old version and it stopped or reported a failure at the end, move only the old app shortcut (for example `~/Applications/MyApp.app`) to the Bin, keep the app's folder in your home folder, and run the installer again ([known issue](https://github.com/CellMigrationLab/LabConstrictor/issues/34)). +- **Linux.** On Linux, running the installer with `-u` updates in place only if the previous install finished; otherwise delete `/pkgs` or uninstall the app and install it again. + +## Uninstall an app + +Uninstalling deletes the app's install folder and everything in it: move anything you saved there to another folder first. + +- **Windows.** Open Settings > Apps > Installed apps, find the app, click the three dots next to it and choose Uninstall. You can also double-click `Uninstall-.exe` in the app's install folder. If the app is still listed afterwards, see [Troubleshooting an installed app](troubleshooting_installed_app.md). +- **macOS and Linux.** Open a terminal and run the `uninstall.sh` script of the app's install folder (the folder you chose when you installed it), for example `bash ~/labconstrictor/MyApp/uninstall.sh`. It removes the app's shortcut (from the Applications folder of your home folder on macOS, from your applications menu on Linux), takes the app out of the tools list of napari, Fiji and QuPath, and deletes the install folder. + +## Where the app is listed + +If the app ships tools for napari, Fiji or QuPath, the installer registers them with LabConstrictor Tools and passes the `hosts:` line of the app's `labconstrictor-app.yaml` (the installer bundles that file). A host lists the app only if the line names it: with `hosts: [notebook, napari]` the app is listed in napari, and not in Fiji or QuPath. Without the file, or without a `hosts:` line, the app is registered without hosts, every host lists it, and `menuinst_debug.log` in the install folder says so (`'' declares no hosts, so it is listed in every host; ...`). + +To run the tools, install the plugin for your image software once: see [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). + +## Next + +Open the app and start working: [Use notebooks after installation](notebook_usage.md). If something goes wrong, see [Troubleshooting an installed app](troubleshooting_installed_app.md). diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/installer_images.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/installer_images.md new file mode 100644 index 0000000..e17f9c6 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/installer_images.md @@ -0,0 +1,45 @@ +# Customise the installer images + +The generated installer and desktop app can be customised with you own images. This will help to give your app a more professional look and feel. This customisation is optional and can be done when initialising your repository or at any time later. + +You can provide the following images for customisation: + +| Image Type | Recommended Size | Format | Description | +|------------|------------------|--------|-------------| +| Logo | 256x256 pixels | PNG | This image will be used in the executable installer and on the created desktop app. | +| Banner | 164x314 pixels | PNG | This vertical image will be used as a banner in the installer. | +| Header | 150x57 pixels | PNG | This image will be used as the header in the installer. | + +When preparing your images, please ensure they meet the recommended size and format for optimal display. Here are some examples of custom images used in an installer: + +## Logo +![LabConstrictor Logo](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/LabConstrictor_Logo.png) + +## Banner +![LabConstrictor Banner](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/LabConstrictor_Banner.png) + +## Header +![LabConstrictor Header](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/LabConstrictor_Header.png) + +## Default installer + +In case you do not provide any images during the initialisation of your repository, default placeholder images will be used: + +![Default Installer Images](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Customisation_Default.png) + +## Customised installer + +When you provide your own images, the installer will reflect your custom branding: + +![Customised Installer Images](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Customisation_Custom.png) + +--- + +
+ +[← Previous](executable_creation.md)            +[🏠 Home](README.md)            +[Next →](app_manifest.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_requirements.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_requirements.md new file mode 100644 index 0000000..ac4a480 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_requirements.md @@ -0,0 +1,112 @@ +# Generate the requirements of your notebook + +You can get your Jupyter notebook’s requirements automatically with Option 1 or manually with Option 2. + +* **Option 1 (Automated):** Recommended if you need to generate requirements from scratch. +* **Option 2 (Manual):** Recommended if you already have a versioned `requirements.txt` file, as it will be faster. + +--- + +## Option 1: Automated Extraction of Requirements + +### 1. Open the Requirements Generator Notebook + +**⚠️ IMPORTANT:** You will need to choose the option based on the environment you used to run the target notebook whose requirements you want to extract. + + * Did you ran your notebook locally on your machine (with Conda/VirtualEnv)? ➡️ Locally + * Did you ran your notebook on Google Colab? ➡️ Online + +In both cases the Python environment that you use for the notebook, needs to run without errors. Knowing this please choose the option that best suits your case: + +* **Locally:** Go to the [Requirements_Generator.ipynb](../notebooks/Requirements_Generator.ipynb) notebook, download it (clicking on the button indicated on the screenshot below ⬇️) and open it in your local Python environment (conda or virtualenv). + > **Note**: When using it locally, the Python environment where you open the requirements generator notebook needs to be exactly the one you use to run the target notebook whose requirements you want to extract. For example, if you have multiple conda environments, you need to make sure that you use the same conda environment that you use to run the target notebook. + +![Download Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Download_Notebook.png) + +* **Google Colab:** Open the notebook directly in Google Colab by opening the [Requirements Generator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Generator.ipynb). + +### 2. Run the Requirements Generator + +Follow the instructions provided inside the notebook to generate the `requirements.yaml` file. You will be prompted to provide the path to the notebook file you wish to analyse. + +--- + +## Option 2: Manual Extraction of Requirements + +### 1. Create a `requirements.yaml` File + +You will need to create a `requirements.yaml` file similar to the [example requirements.yaml file](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/templates/requirements.yaml). This file must contain the following three fields: + +* **`dependencies`:** A list of all packages used in the notebook along with their versions. The list needs to be indexed with a hyphen (`-`) followed by a space before each package. +* **`python_version`:** The version of Python used in the notebook (e.g., `3.11.1`). +* **`description`:** A short description of the notebook and its purpose. + +**Example File Content:** + +```yaml +dependencies: + - pandas==2.2.2 + - ipython==7.34.0 + - tqdm==4.67.1 +description: This notebook is for analyzing cell migration data... +python_version: 3.11.1 + +``` + +### 2. Open the Requirements Validator Notebook + +We recommend using **Google Colab** for this step, as you do not need a specific Python environment to run the validator. + +* **Google Colab (Recommended):** Open the notebook directly by opening the [Requirements Validator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Validator.ipynb). +* **Locally:** Download the [Requirements_Validator.ipynb](https://raw.githubusercontent.com/CellMigrationLab/LabConstrictor/main/.tools/notebooks/Requirements_Validator.ipynb) and open it in any Python environment that has `ipywidgets` installed. + +### 3. Run the Requirements Validator + +Follow the instructions provided inside the notebook to validate your file. You will need to provide the path to your newly created `requirements.yaml` file when prompted. + +--- + +## What happens next: the lock file + +When you push a notebook with its `requirements.yaml`, the workflow **Updates on notebook change** merges the requirements of every notebook into `requirements.txt` (plus `requirements_gpu.txt` and, if a notebook needs them, `requirements-windows.txt`, `requirements-linux.txt` or `requirements-macos.txt`). + +The installer uses `requirements_gpu.txt` when it finds an NVIDIA GPU on Windows or Linux. In that file `tensorflow` becomes `tensorflow[and-cuda]` on Linux only: TensorFlow has had no Windows GPU build since version 2.10, and its CUDA packages exist only for Linux, so Windows keeps plain `tensorflow` (CPU). + +### When notebooks ask for different versions of a package + +The merge never changes a notebook's requirement silently. Requirements are kept as written (`numpy>=1.24` stays `numpy>=1.24`), and the requirements of several notebooks are combined (`numpy>=1.24,<2`). The workflow stops, and no requirements file is written, when: + +* two notebooks pin a package to different versions (`numpy==1.26.4` and `numpy==2.0.0`); +* a pin does not meet another notebook's requirement (`numpy==2.0.0` and `numpy<2`); +* no version meets all the requirements (`numpy<2` and `numpy>=2.1`). + +The log of the **Run merge script** step names the package, every notebook and its requirement. Then either: + +* **make the notebooks agree:** change their `requirements.yaml` to a version that works for every notebook; or +* **decide explicitly** in `requirements_overrides.yaml`, at the top of the repository, which requirement every notebook gets, and why: + +```yaml +overrides: + numpy: + use: "==2.0.0" + reason: "Notebook A was re-run with numpy 2.0.0 and gives the same results; notebook B needs 2.0." +``` + +The decision and its reason are written at the top of the generated requirements files. Pushing `requirements_overrides.yaml` runs the workflow again. A release also stops while a conflict is not resolved. Requirements with different platform markers (`; sys_platform == "win32"`) are kept as separate lines, and `NumPy`, `numpy` and `num_py` count as the same package, as for pip. + +It then writes a **lock file** next to each of them (`requirements.lock.txt`, ...). A lock file lists every package the installer installs, including the packages your packages depend on, each with its exact version, for Windows, macOS and Linux. The installer installs the lock file, so every installation of a release gets the same versions. + +* A lock file changes only when its requirements file, the Python version or the JupyterLab version changes. Pushing a notebook without new requirements does not move any version. +* To move every package to its newest version, delete the `requirements*.lock.txt` files and run **Updates on notebook change** by hand (**Actions > Updates on notebook change > Run workflow**). +* If the requirements cannot be locked, the workflow shows a warning and the installer installs the plain `requirements.txt` instead. + +--- + +
+ +[← Previous](accept_pull_request.md)            +[🏠 Home](README.md)            +[Next →](notebook_upload.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_upload.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_upload.md new file mode 100644 index 0000000..3e00273 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_upload.md @@ -0,0 +1,178 @@ +# Add or update a notebook + +If you want to add or update a notebook in your project repository, just follow these steps to upload it smoothly. + +## 1. Prepare your notebook + +To ensure your notebook works with the versioning tracking provided by the LabConstrictor application, please follow these three steps to prepare your notebook: + +1. First, create a cell at the top of your notebook (see our [JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md) if you need help with that). +2. Then, copy and paste the code below into that cell. +3. Finally, update the `current_version` variable with the version of your notebook (for example, "0.0.2") and the `notebook_name` variable with the name of your notebook file (without the .ipynb extension). + +> IMPORTANT NOTE: Each time you change the notebook's logic, update the version number on `current_version` variable so users can see there is a new version. + +```python +# @markdown Run this cell to check this notebook's version. + +current_version = "0.0.1" +notebook_name = "Notebook_template" # Replace with the actual notebook name + +# First of all check if ipywidgets is installed, if not through an informative error +try: + import ipywidgets as widgets +except ImportError: + raise ImportError("ipywidgets is not installed. Please install it using 'pip install ipywidgets' or 'conda install -c conda-forge ipywidgets'.") + +from IPython.display import display + +try: + from google.colab import output + output.enable_custom_widget_manager() + + try: + import yaml + except ImportError: + raise ImportError("pyyaml is not installed. Please install it using 'pip install pyyaml' or 'conda install -c conda-forge pyyaml'.") + + import requests + import base64 + + # Create widgets + github_repo = widgets.Text( + value="", + description="*GitHub Repository URL:", + placeholder="e.g https://github.com/username/repository", + layout=widgets.Layout(width="70%"), + style={'description_width': '150px'}, + ) + + github_token = widgets.Password( + value="", + description="*Personal Access Token:", + placeholder="[Disabled] e.g. ghp_XXXXXXXXXXXXXXXXXXXX", + disabled=True, + layout=widgets.Layout(width="70%"), + style={'description_width': '150px'}, + ) + + test_button = widgets.Button( + description="Test Connection", + button_style='success', + ) + + output_area = widgets.HTML() + + # By default the repository is considered public + if "repository_is_private" not in globals(): + repository_is_private = False + elif repository_is_private: + github_token.disabled = False + github_token.placeholder = "e.g. ghp_XXXXXXXXXXXXXXXXXXXX" + + def on_test_button_clicked(b): + global repository_is_private + + # Check that the GitHub repository URL is provided + if not github_repo.value: + output_area.value = "⚠️ Please provide a GitHub repository URL." + return + + # Get the owner and repo name from the URL + repo_url = github_repo.value.rstrip('/') + github_owner, github_repo_name = repo_url.split('/')[-2:] + + # Online version checking file path + version_file_path = "notebooks/notebook_latest_versions.yaml" + version_url = f"https://api.github.com/repos/{github_owner}/{github_repo_name}/contents/{version_file_path}" + + # Do an initial request to check if the repository is public + if not repository_is_private: + version_response = requests.get(version_url) + if version_response.status_code == 404: + repository_is_private = True + github_token.disabled = False + github_token.placeholder = "e.g. ghp_XXXXXXXXXXXXXXXXXXXX" + output_area.value = f"⚠️ We have detected that the repository might be private. Please provide a Personal Access Token and click 'Test Connection' again." + return + else: + headers = {"Accept": "application/vnd.github.v3+json"} + if not github_token.value: + output_area.value = "⚠️ Personal Access Token is required for private repositories." + return + headers["Authorization"] = f"token {github_token.value}" + + version_response = requests.get(version_url, headers=headers) + + # Check the response status + if version_response.status_code == 200: + content = version_response.json()['content'] + decoded_content = base64.b64decode(content).decode('utf-8') + config = yaml.safe_load(decoded_content) + # notebook_latest_versions.yaml groups the notebooks by folder: {"": {"": ""}} + latest_version = next((str(group[notebook_name]) for group in (config or {}).values() + if isinstance(group, dict) and notebook_name in group), "") + + output_area.value = (f"Notebook version: `{current_version}`
" + f"Latest version available: `{latest_version}`
") + + if latest_version == "": + output_area.value += "⚠️ This notebook is not listed in the version file.
" + elif current_version == latest_version: + output_area.value += "✅ This notebook is up-to-date.
" + else: + output_area.value += f"⚠️ A new version of this notebook is available." + else: + output_area.value += "⚠️ Could not retrieve the version file.
" + + test_button.on_click(on_test_button_clicked) + # Widget layout + widget_box = widgets.VBox([github_repo, github_token, test_button, output_area]) + display(widget_box) +except ImportError: + display(widgets.HTML('To check the notebook version, please go to the Welcome notebook.')) +``` + +## 2. Generate the requirements file + +Follow the steps in the [Obtain requirements of the notebook](notebook_requirements.md) guide to create the `requirements.yaml` file for your notebook. + +## 3. Upload to the repository + +1. Open the [LabConstrictor website](https://labconstrictor-form.streamlit.app/). If you see a `Zzzz` message for inactivity, click `Yes, get this app back up!`. +2. Select **Upload/Update notebook**. +3. Upload your notebook file (`.ipynb`) and the `requirements.yaml` file you created. +4. Click **➕ Validate & Add Submission**. If the notebook and its requirements pass the checks, the notebook appears in the **📃 Submission list**. You can repeat steps 3 and 4 to add more notebooks to the list before uploading. +5. In the **⬆️ Upload it to GitHub** section, enter your repository URL and your personal access token. + * *(Don't have a token? See [How to create a personal access token](personal_access_token.md))* +6. Click **🚀 Create pull request**. + + +## 4. Merge and Verify + +If you need help merging the pull request, see the [Accept a Pull Request](accept_pull_request.md) guide for instructions. An automatic workflow will check your notebook and its dependencies. +* **Check Status:** See [How to check workflow status](workflow_status.md). +* Failure Protocol: If the merged requirements cannot be installed, the system automatically undoes the merge. Check the logs, fix the problem in your local notebook or requirements, and upload again. +* If notebooks ask for different versions of the same package, the workflow stops before anything is installed and the requirements files are not changed. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package). + +--- + +## How to update an existing notebook + +Updating a notebook works the same way as adding a new one: + +1. Bump the version: In the top cell of your notebook, increase the `current_version` (for example, from '1.0.0' to '1.0.1'). +2. Regenerate requirements: Run the bottom cell to make sure `requirements.yaml` matches the new version number. +3. Upload: Use the [LabConstrictor App](https://labconstrictor-form.streamlit.app/) to upload your file. + * *Ensure the filename matches the existing one in the repository exactly.* + +--- + +
+ +[← Previous](notebook_requirements.md)            +[🏠 Home](README.md)            +[Next →](executable_creation.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_usage.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_usage.md new file mode 100644 index 0000000..10ff7a6 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/notebook_usage.md @@ -0,0 +1,44 @@ +# Use notebooks after installation + +After you install the desktop application, this guide will show you how to use the Jupyter notebooks that come with it. + +## 1. Launching the Application + +To open the application, go to the Start Menu (Windows), the Applications folder (macOS) or your applications menu (Linux). Search for the application name and click its icon to start it. + +## 2. Welcome Notebook + +When you start the application, a terminal will pop up. + +> Don't be scared by the terminal, it is normal: it keeps your Jupyter Lab session running. **Do not close the terminal** until you have finished working with your notebooks. When you have, stop the Jupyter Lab session with **File > Shut Down** in Jupyter Lab (or click on the terminal window and press `Ctrl+C`). The terminal then asks you to press `Enter`, and closes. + +After some seconds, Jupyter Lab will open in your default web browser. The welcome notebook will appear automatically: + +![Welcome Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Welcome_Notebook.png) + +### Updating a notebook + +When a newer version of a notebook is published, the Welcome notebook shows **Update** next to it. Updating replaces your copy of the notebook, so before anything changes it asks you to confirm, and it keeps your current copy, with your changes and outputs, as `.backup-.ipynb` in the same folder. Close the notebook's tab before updating: otherwise JupyterLab can save the old copy over the new one. If the download fails, your notebook is not changed. + +## 3. How to Run Notebooks? + +You might be used to work with notebooks on JupyterLab (in case you need some guidance on JupyterLab check [this guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md)). Still, LabConstrictor uses some features that can slightly change how you interact with notebooks. Please check [this guide](code_hiding.md) to understand how to run notebooks packaged with LabConstrictor. + +## 4. Accessing your Notebooks + +Once you run the welcome notebook, a dashboard will show a list of available notebooks. It looks similar to the screenshot in the [Welcome Notebook](#2-welcome-notebook) step. + +In the last column of the dashboard, you'll see a button called `Open the notebook`. Click it to open that notebook in a new tab and run it just like you did with the welcome notebook. + + +--- + + +
+ +[← Previous](download_executable.md)            +[🏠 Home](README.md)            +Next → + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/template_synchronization.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/template_synchronization.md new file mode 100644 index 0000000..1c512ea --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/template_synchronization.md @@ -0,0 +1,82 @@ +# Enable automatic LabConstrictor template updates + +LabConstrictor periodically checks the main template for improvements. When an update is available, the **Sync with Template Repository** workflow prepares the changes in a pull request so you can review and merge them safely. + +You will need to do a one-time GitHub setup to create a token that allows LabConstrictor to update your repository. This token described below is limited to the repository you select. LabConstrictor does not need access to your other repositories. + +## What do I need to do? + +Follow the same instructions that are given in the following video and instructions below. + +## Step 1: Create the synchronization token + +![GIF showing the token creation](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Synchronisation_Token_Creation.gif) + +Follow steps on the GIF or click on [this link](https://github.com/settings/personal-access-tokens/new?name=LabConstrictor+Sync&description=Allows+LabConstrictor+to+prepare+template+update+pull+requests.&expires_in=365&contents=write&pull_requests=write&workflows=write) and follow the steps below: + +1. Under **Resource owner**, select the owner of your LabConstrictor repository. +2. Under **Repository access**, select **Only select repositories**. +3. Select your LabConstrictor repository. +4. Choose an expiration period that suits you. The prefilled suggestion is 365 days. +5. Confirm these repository permissions: + - **Contents:** Read and write + - **Pull requests:** Read and write + - **Workflows:** Read and write +6. Select **Generate token**. +7. Copy the generated token. + +> GitHub shows the complete token only once. Keep the page open until you have saved it in Step 2. + +## Step 2: Save the token as a repository secret + +![GIF showing the secret creation](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Synchronisation_Secret_Creation.gif) + +1. Open your LabConstrictor repository. +2. Select **Settings**. +3. In the left sidebar, select **Secrets and variables**, then **Actions**. +4. Select **New repository secret**. +5. Enter this exact name: + + ```text + LABCONSTRICTOR_SYNC_TOKEN + ``` + +6. Paste the token into the **Secret** field. +7. Select **Add secret**. + +> GitHub encrypts repository secrets. The token will not be displayed in the repository or in normal workflow logs. + +## Step 3 (situational): One-time step for repositories created before template version 0.1.12 + +An older synchronization workflow does not yet reference `LABCONSTRICTOR_SYNC_TOKEN`. If you already saw an error saying that a GitHub App cannot create or update a workflow without `workflows` permission, make this small edit once: + +1. Open [`.github/workflows/sync_template.yml`](../../.github/workflows/sync_template.yml) in your repository. +2. Select the pencil icon to edit the file. +3. Copy and paste all the lines from the [LabConstrictor original workflow](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.github/workflows/sync_template.yml). + +4. Select **Commit changes** and commit directly to the default branch. +5. Run **Sync with Template Repository** again. + +The migration will then install the complete updated workflow automatically. This manual edit is only needed once for repositories whose existing workflow predates token integration. + +## Renewing an expired token + +When the token expires: + +1. Create a replacement token using Step 1. +2. Open **Settings → Secrets and variables → Actions**. +3. Select `LABCONSTRICTOR_SYNC_TOKEN`. +4. Select **Update secret** and paste the replacement token. +5. Run synchronization again. + +You do not need to edit the workflow again. + +--- + +
+ +[← Create repository](create_repository.md)            +[🏠 Documentation home](README.md)            +[Initialise repository →](initialise_repository.md) + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/tools_bridge.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/tools_bridge.md new file mode 100644 index 0000000..d283aa6 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/tools_bridge.md @@ -0,0 +1,81 @@ +# 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 +function signatures. Nothing changes for apps that do not declare tools. + +This page covers what the template does: where you declare the tools and what the installer does with them. Two other guides cover the rest: + +- [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/): the inputs + and outputs a tool can have, how to lay out its form, what each program supports, and how to test a tool. +- [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/): what the people + who install your app do to run its tools, with the install steps of the + [napari plugin](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/napari/), the + [Fiji plugin](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/fiji/) and the + [QuPath extension](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/qupath/). + +## Declare your tools + +1. Add a module named `_lc_tools` next to your package under `src/` (so `src/mytool_lc_tools/__init__.py` for + the package `mytool`). The installer registers tools only from a module with exactly this name. Declare tools in it with typed + functions, and import your science code **inside** the functions: + + ```python + from typing import Annotated + from labconstrictor_tools import Image, ImageOut, Min, tool + + @tool("Gaussian blur") + def blur(image: Image, sigma: Annotated[float, Min(0)] = 2.0) -> ImageOut: + from mytool.filters import gaussian + return gaussian(image, sigma) + ``` + + Keep the module light: it is imported to read the tool list, so heavy imports at the top slow every start. +2. Import `labconstrictor_tools` only in `_lc_tools`, or inside functions, if you can. The rest of your package then also works + where LabConstrictor Tools is not installed: a notebook run on Google Colab, a copy of the package used elsewhere, or an installation where + Tools failed to install. An import at the top of your package does not stop the installation, because the installer installs Tools before + it checks that your package can be imported. +3. Name the programs your tools work in under `hosts:` in `labconstrictor-app.yaml`: see [Describe your app for the App Centre](app_manifest.md). +4. Test your tools before you publish a release, as [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/) + shows (`labconstrictor-tools check` and `labconstrictor-tools test`). + +## What the installer does + +The installer's `post_install` step: + +1. installs your package; +2. if your package has a `_lc_tools` module, installs LabConstrictor Tools; +3. checks that your package can be imported; +4. registers the app (`labconstrictor-tools register ...`) with the version from the `version:` line of `construct.yaml` and the hosts of + `labconstrictor-app.yaml`. + +When the app is uninstalled, `pre_uninstall` unregisters it. + +A failure in step 2 or 4 is written as a `WARNING` to `menuinst_debug.log` in the install folder, the registration is skipped, and the +installation goes on. The one exception is a package that needs Tools to be imported: then the import check of step 3 fails, as it should. + +The Windows step (`post_install.bat`) runs in the template's automated tests on a Windows machine, and people have installed apps on Windows +and macOS from a clean system. + +### Which LabConstrictor Tools the installer installs + +LabConstrictor Tools is not on PyPI yet. The installer downloads the GitHub archive of one release tag of LabConstrictor-Tools, a plain zip +file, so the user's computer does not need git. The tag is pinned: two installers built from the same app release install the same Tools, +and a change to Tools does not reach new installations until the pin is moved on purpose. Template updates move the pin in your app. + +The tag is the value of `LC_TOOLS_PIN` in both scripts: +[app/bash_bat_scripts/post_install.sh](../../app/bash_bat_scripts/post_install.sh) (`LC_TOOLS_PIN="..."`) and +[app/bash_bat_scripts/post_install.bat](../../app/bash_bat_scripts/post_install.bat) (`SET "LC_TOOLS_PIN=..."`). + +To install Tools from somewhere else, set the environment variable `LC_TOOLS_SPEC` when the installer runs: a wheel, a git URL, a mirror, or +the name `labconstrictor-tools` once it is on PyPI. It replaces the pin completely. + +**Move the pin (template maintainers).** Create and test the tag in LabConstrictor-Tools (the procedure is in its `docs/OPERATIONS.md`). +Change `LC_TOOLS_PIN` in both scripts of the template, and in the copies under `.template_sync/resources/` of the latest migration if it has +them (the test `test_resources_are_identical_to_the_template_files` fails when they differ). Then write a migration that changes the string in +the apps' scripts, and bump `template_version`. + +## If something does not work + +- `menuinst_debug.log` in the app's install folder says what the installer did with your tools. +- `labconstrictor-tools doctor` checks the Tools installation, and `labconstrictor-tools logs` shows its log. diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/troubleshooting.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/troubleshooting.md new file mode 100644 index 0000000..1c66d13 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/troubleshooting.md @@ -0,0 +1,75 @@ +# Troubleshooting repository setup + +Problems with your repository on GitHub. For problems with an installed app on your computer, see [Troubleshooting an installed app](troubleshooting_installed_app.md). + +## Synchronisation is failing on GitHub Actions + +The **Sync with Template Repository** workflow needs the encrypted repository secret `LABCONSTRICTOR_SYNC_TOKEN` because template migrations can update files in `.github/workflows/`. Follow the [automatic template synchronization guide](template_synchronization.md) for the complete beginner-friendly setup. + +### The synchronization token is missing + +Create the token and save it under **Settings → Secrets and variables → Actions** with this exact name: + +```text +LABCONSTRICTOR_SYNC_TOKEN +``` + +### GitHub refuses to update a workflow file + +If the error says GitHub is refusing to create or update a workflow without `workflows` permission, ensure the token has all of these repository permissions: + +- **Contents:** Read and write +- **Pull requests:** Read and write +- **Workflows:** Read and write + +Repositories created before template version `0.1.12` also need the one-time workflow edit described in the synchronization guide so the existing workflow starts using the secret. + +### Bad credentials or authentication failed + +The token may have expired or been revoked. Create a replacement token and update the existing `LABCONSTRICTOR_SYNC_TOKEN` secret. + +## The release stops at "check_placeholders.py" + +The release workflow checks, before it builds the installers, that no template placeholder (`PROJECT_NAME`, `PYTHON_PROJ_NAME`, `UNDERSCORED_PROJECT_NAME`, ...) is left in a file the installer ships. An installer built with one would fail on the users' computers (for example `No module named 'PYTHON_PROJ_NAME'` at the end of the installation). + +The log of the failed step lists each file and line. Replace the placeholder there with your app's value: `PYTHON_PROJ_NAME` is the Python package of the app (usually its folder in `src/`), `PROJECT_NAME` the app name. For `app/menuinst/Welcome.ipynb`, edit `.tools/templates/Welcome_template.ipynb` instead: the Welcome notebook is made from it at every release. Commit, then publish the release again. See [migration_0_1_23.md](migration_0_1_23.md). + +## The release stops at "Installers to build" + +The `platforms` job of the release workflow reads `distribution.platforms` in `labconstrictor-app.yaml` to decide which installers to build. It stops when the file is not valid YAML, when `platforms` is not a list, or when it lists none of the systems the release builds installers for: `windows-x86_64`, `linux-x86_64`, `macos-arm64` and `macos-x86_64`. The log of the step says which. Fix `labconstrictor-app.yaml` (see [App Centre manifest](app_manifest.md)), commit, then publish the release again. See [migration_0_1_24.md](migration_0_1_24.md). + +## "The notebooks ask for incompatible package versions" + +The **Run merge script** step of **Updates on notebook change**, or the `merge_requirements.py --check` command of a release, stops when notebooks pin a package to different versions, or ask for versions that no single version meets. Its log lists the package, each notebook and its requirement. Make the notebooks agree, or decide in `requirements_overrides.yaml` which requirement every notebook gets and why, then push it: the workflow runs again. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package) and [migration_0_1_31.md](migration_0_1_31.md). + +If the template synchronization to 0.1.31 created `requirements_overrides.yaml`, its entries keep the versions your app installed until now (the newest of the pins). Check each one with every notebook that uses the package, and replace its reason with yours. + +## Publishing to PyPI fails + +The workflow **Publish the Python package to PyPI** (`publish_pypi.yml`) runs at a release only when the repository variable `PYPI_PUBLISH` is `true` or `testpypi` (see [Upload external code](external_code_upload.md#4-publish-the-code-on-pypi-optional)). Its first job checks and builds the package; its second job uploads it. The installers do not depend on it: a failure here leaves the release and its installers as they are. + +| What you see | What to do | +|---|---| +| Both jobs are grey (skipped) | The variable is missing or has another value. It must be a **variable** (Settings > Secrets and variables > Actions > **Variables**), not a secret, named `PYPI_PUBLISH`, with the value `true` or `testpypi` exactly. | +| `invalid-publisher: valid token, but no corresponding publisher` | The trusted publisher on pypi.org (or test.pypi.org for `testpypi`) does not match this workflow. Check the five fields: owner, repository, workflow `publish_pypi.yml`, environment `pypi`, and the project name. Then re-run the failed job (Actions > the run > **Re-run failed jobs**). | +| `... isn't allowed to upload to project ...` (403) | The name belongs to another PyPI project that this repository is not a publisher of. If it is yours, add the publisher in that project's **Publishing** page; if not, choose another `name=` in `setup.py` (and `distribution.pip`). | +| `PyPI already has ` (or `File already exists`) | That version was uploaded before; a version can be uploaded only once, even after it was deleted. Publish a new release with a higher version. | +| `There is no Python package in src/` | Add your code as a folder with an `__init__.py` in `src/` (see [Upload external code](external_code_upload.md)), or delete the variable `PYPI_PUBLISH`. | +| `... also publishes to PyPI` | Another workflow of the repository uploads to PyPI too. Keep one: delete the variable `PYPI_PUBLISH`, or delete the other workflow. | +| `distribution.pip of labconstrictor-app.yaml is ..., but setup.py names the package ...` | Make the two names the same. | +| `PyPI refuses a package whose dependency is a URL` | `setup.py` lists a dependency as `name @ git+https://...`. Publish that dependency on PyPI and name it with a version, or move the URL to `requirements.txt` (the installer still installs it; the PyPI package leaves it out). | +| `setup.py still has the template placeholder ...` | Replace the placeholder in `setup.py` (the log says which), commit, and publish a new release. | +| The upload job waits | The `pypi` environment has required reviewers (Settings > Environments > pypi): one of them approves the upload in the run. | + +After a fix, re-run the failed jobs of the run if nothing in the repository changed (a publisher fixed on pypi.org); otherwise publish a new release. See [the design note of template 0.1.25](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_25.md). + +--- + +
+ +[← Previous](workflow_status.md)            +[🏠 Home](README.md)            +[Next →](personal_access_token.md) + + +
diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/troubleshooting_installed_app.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/troubleshooting_installed_app.md new file mode 100644 index 0000000..c91847b --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/troubleshooting_installed_app.md @@ -0,0 +1,68 @@ +# Troubleshooting an installed app + +Problems with an app on your computer, after you installed it. For problems with your repository on GitHub, see [Troubleshooting repository setup](troubleshooting.md). + +## App still appears in the Windows Installed apps list after uninstalling + +On Windows, it may happen that, after uninstalling the app from `Settings > Apps > Installed apps` as explained in [Uninstall an app](install.md#uninstall-an-app), the app still appears in the list and does not allow you to uninstall it again, showing a message like: + +![Uninstall error message](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/troubleshooting/Not_Uninstall.png) + +The solution is to go to the Control Panel and uninstall it from there. To do this: + +1. Open the Control Panel. You can search for it in the Windows search bar. +2. Go to `Programs > Programs and Features`. +3. Find the LabConstrictor-based app in the list, right-click on it, and select `Uninstall`. +4. A message may appear saying something like: "An error occurred while trying to uninstall xxx. It might have already been uninstalled." Click `Yes` to confirm. + +This should remove the app even if the previous error message appears. + +## Windows asks for administrator rights for python.exe while uninstalling + +Uninstalling an app made with template 0.1.20 or earlier may show a User Account Control prompt: "Do you want to allow this app from an unknown publisher to make changes to your device? python.exe", with the program location `"\python.exe" -m conda.core.initialize ...`. + +The prompt is not needed. Click **No**. The uninstaller then shows a "Failed to clean AutoRun" error with Abort, Retry and Ignore: click **Ignore**. The uninstall finishes normally and nothing outside the app folder is changed. Clicking **Yes** does not help: the same step fails again and shows the same error, and **Retry** asks a second time. + +Do not click **Abort**, even though it is the default button: it stops the uninstall halfway and leaves the app folder on disk. If that happened, run `Uninstall-.exe` in the app folder again. + +The cause is a conda bug in the tool that built the installer (conda/conda#16856). Installers built with template 0.1.21 or later do not have it; see [migration_0_1_21.md](migration_0_1_21.md). + +## The notebook fails with "No module named ..." although the installation finished + +If someone once ran `python -m ipykernel install --user` on the computer (common with Anaconda or pip setups), Jupyter has a personal "python3" kernel in the user's folder (`~/.local/share/jupyter/kernels/python3` on Linux, `~/Library/Jupyter/kernels/python3` on macOS, `%APPDATA%\jupyter\kernels\python3` on Windows). Apps made with template 0.1.23 or earlier then run their notebooks in that other Python, and the first cell that imports the app fails with `ModuleNotFoundError: No module named ''`. + +Install a release made with template 0.1.24 or later: its launcher always uses the app's own kernel. Until then, removing that personal kernel folder also works, but it affects the other Jupyter installations that use it. See [migration_0_1_24.md](migration_0_1_24.md). + +## My changes to a notebook are gone after an update + +Since template 0.1.31, the **Update** button of the Welcome notebook keeps your copy before it replaces a notebook: look for `.backup-.ipynb` in the same folder, and open it in JupyterLab. Apps made with template 0.1.30 or earlier replace the notebook without a copy. + +## JupyterLab does not start because Windows reports an ASN.1 certificate error + +LabConstrictor-based installers include a TLS-resilient launcher. It attempts +native operating-system certificate verification before JupyterLab imports +Tornado and provides a verified CA-bundle fallback when a malformed Windows +certificate-store entry cannot be parsed. SSL and hostname verification are +never disabled. + +The constructor environment intentionally does not include +`pip-system-certs`. Its automatic Python startup hook can fail before the +application launcher has an opportunity to select the verified fallback. +Post-install pip commands instead use an explicit CA bundle while preserving +certificate verification. + +Diagnostic information is written to `launcher_debug.log` and +`menuinst_debug.log` in the installation directory. Maintainers can run the +same preflight used by the installer with: + +```text +\python.exe \PROJECT_NAME\launch_jupyter.py --self-test +``` + +The self-test reports the project-specific CA override variable. It is derived +from the application name by replacing punctuation and spaces with underscores +and converting it to uppercase, for example `MY_PROJECT_CA_BUNDLE`. All +LabConstrictor-based applications also accept the shared +`LABCONSTRICTOR_CA_BUNDLE` variable. Set either variable to an organization PEM +bundle before installation or launch when a private certificate authority is +required. diff --git a/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/workflow_status.md b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/workflow_status.md new file mode 100644 index 0000000..edd8476 --- /dev/null +++ b/.template_sync/resources/v0_1_36_to_v0_1_37/previous/.tools/docs/workflow_status.md @@ -0,0 +1,45 @@ +# Check the status of GitHub workflows + +When you upload a notebook or make a release, GitHub Actions starts a workflow to check your code and build the installers. The template synchronization workflow additionally requires the one-time [`LABCONSTRICTOR_SYNC_TOKEN` setup](template_synchronization.md). + +## 1. Monitor the progress + +1. Go to the **Actions** tab in your GitHub repository. +2. You’ll see a list of recent workflows. Find the one that matches your latest commit or release. +3. Check the status icon next to the workflow name: + +![GitHub Actions Status Icons](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/actions_status_icons.png) + +## 2. How to debug a failure + +If the workflow fails, don’t worry. The system creates an error log that’s ready for you to use. + +1. **Download the Log:** + * Click on the failed workflow run. + * Scroll down to the bottom of the page to the **Artifacts** section. + * Download the log file listed there (it is a plain `.log` text file, nothing to unzip). + +2. **Copy & Paste into AI:** + * Open the log file in any text editor. + * **This file is already formatted as a prompt.** It includes all the context and error details you need. + * Just **copy all the text** and paste it into your preferred AI tool (like ChatGPT, Gemini, or Claude). The AI will explain the error and show you how to fix your notebook or `requirements.yaml`. + +--- + +### Best practice for large updates + +If you’re planning a big update, like changing several notebooks or adding complex dependencies, don’t push straight to the main branch. + +Instead, **create a new branch**, make your changes there, and check that the workflows pass (✅) before merging into the main branch. This helps keep your live app working. + +--- + +
+ +← Previous            +[🏠 Home](README.md)            +[Next →](troubleshooting.md) + + +
+ diff --git a/.tools/docs/migration_0_1_37.md b/.tools/docs/migration_0_1_37.md new file mode 100644 index 0000000..e83c5a7 --- /dev/null +++ b/.tools/docs/migration_0_1_37.md @@ -0,0 +1,37 @@ +# Template 0.1.37: the user guides, checked and rewritten + +Design note for the 0.1.37 migration (`.template_sync/migrations/v0_1_36_to_v0_1_37.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 website imports the template's guides into three tracks (use an app, build an app, connect an app). A review against the template, the repository form and the installer found: + +* wrong advice: `workflow_status.md` said to test a big change on a branch first, but the workflows run only on pushes to `main` (and by hand); `notebook_upload.md` asked to "run the bottom cell" so that `requirements.yaml` matches the new notebook version, a cell that does not exist; +* missing facts a reader needs: the form accepts only `package==version` dependencies and only a classic `ghp_` token; every notebook of an app must use the same `python_version`; the generator saves `_requirements.yaml`; +* the guides a first-time reader follows to the end (install, initialise, requirements, upload, installers) did not say what you need, how to check that it worked and what to do if it does not; the website checks for these sections; +* `template_synchronization.md` linked the wrong previous and next pages; `tools_bridge.md`, the first page of the "Connect an app" track, began with what the page covers and kept a paragraph for template maintainers; +* history, design-note links and implementation detail in pages written for app users. + +Some of these pages could not change before: older migrations install them as frozen copies, and their tests compared the live page with those copies. + +## 2. What changes + +Seventeen guides in `.tools/docs/` are replaced (the list is `FILES` in the migration): `accept_pull_request.md`, `app_manifest.md`, `before_getting_started.md`, `create_repository.md`, `executable_creation.md`, `external_code_upload.md`, `initialise_repository.md`, `install.md`, `installer_images.md`, `notebook_requirements.md`, `notebook_upload.md`, `notebook_usage.md`, `template_synchronization.md`, `tools_bridge.md`, `troubleshooting.md`, `troubleshooting_installed_app.md` and `workflow_status.md`. + +Headings and anchors that other pages or the website link to are kept, in particular the system sections of `install.md` ("Install on Windows", "Install on a Mac", "Install on Linux"), which the website shows on each app page. `install.md` renames "Before you install" to "Before you start". No code changes. + +## 3. What the migration does + +* Each guide is replaced by the 0.1.37 page when it is still the 0.1.36 template file, compared with LF line endings (the frozen copies are in `.template_sync/resources/v0_1_36_to_v0_1_37/previous/`). The file keeps its own line endings. +* `external_code_upload.md` is also recognised when the repository form wrote the app's Python package name in place of `PYTHON_PROJ_NAME`; the new page gets the same name. +* A guide the app changed is left as it is (`SKIPPED`, with a note to compare it with the template's page). Many apps have their own `troubleshooting.md`, so it is often skipped. +* A missing guide 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 guide, compare it with the template's page and take what you want. + +## 5. What is checked here + +* Tests (`tests/test_template_sync_0_1_37.py`): the resources are the live guides and differ from the 0.1.36 ones; a 0.1.36 app reaches the live guides with LF and CRLF line endings, and a second run changes nothing; a customised guide is skipped; a missing guide is not created; `external_code_upload.md` with a package name; the sync from 0.1.36 and the chain from older versions. +* The older tests compare with the 0.1.36 guides (`tests/_v0_1_37.py`, `before_0_1_37`). From c14be35abac694a59017bdc238374a6831eb98a2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:32:26 +0000 Subject: [PATCH 11/12] Tests: older migration tests compare with the 0.1.36 guides (tests/_v0_1_37.py) before_0_1_37 gives the frozen 0.1.36 copy of a guide that is the 0.1.37 page; it is chained into before_0_1_36, and the 0.1.26, 0.1.35, 0.1.36 and token-integration tests use it where they read a live guide. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- tests/_v0_1_36.py | 3 ++ tests/_v0_1_37.py | 38 +++++++++++++++++++ tests/test_template_sync_0_1_26.py | 17 ++++++--- tests/test_template_sync_0_1_35.py | 3 +- tests/test_template_sync_0_1_36.py | 12 ++++-- tests/test_template_sync_token_integration.py | 4 +- 6 files changed, 67 insertions(+), 10 deletions(-) create mode 100644 tests/_v0_1_37.py diff --git a/tests/_v0_1_36.py b/tests/_v0_1_36.py index d02675b..635ab9f 100644 --- a/tests/_v0_1_36.py +++ b/tests/_v0_1_36.py @@ -15,6 +15,8 @@ from pathlib import Path from types import ModuleType +from _v0_1_37 import before_0_1_37 + ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_35_to_v0_1_36.py" @@ -38,6 +40,7 @@ def template_bytes(relative: Path | str) -> 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.""" + data = before_0_1_37(relative, data) migration = _migration() relative = Path(relative) if relative not in migration.EDITS: diff --git a/tests/_v0_1_37.py b/tests/_v0_1_37.py new file mode 100644 index 0000000..913dfd6 --- /dev/null +++ b/tests/_v0_1_37.py @@ -0,0 +1,38 @@ +"""Helper of the tests: a live template file as it was before template 0.1.37. + +Template 0.1.37 replaces seventeen user guides in .tools/docs whole (FILES of the migration). The tests of the older migrations compare with +the live files; `before_0_1_37` gives the bytes of a live file without the 0.1.37 change (the frozen 0.1.36 copy when the file is the 0.1.37 +page), so they keep checking what they checked. The 0.1.37 changes are tested in test_template_sync_0_1_37.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_36_to_v0_1_37.py" + + +def _migration() -> ModuleType: + spec = importlib.util.spec_from_file_location("migration_0_1_37_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_37(relative: Path | str, data: bytes) -> bytes: + """`data` (a live template file at `relative`) without the 0.1.37 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.37 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_26.py b/tests/test_template_sync_0_1_26.py index 7f90431..1dd7013 100644 --- a/tests/test_template_sync_0_1_26.py +++ b/tests/test_template_sync_0_1_26.py @@ -13,6 +13,8 @@ from pathlib import Path from types import ModuleType +from _v0_1_37 import before_0_1_37 + ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_25_to_v0_1_26.py" @@ -38,6 +40,11 @@ def lf(path: Path) -> str: return path.read_bytes().decode("utf-8").replace("\r\n", "\n") +def at_0_1_36(relative: Path | str) -> str: + """The template file at `relative` without the 0.1.37 change (tests/_v0_1_37.py), with LF line endings.""" + return before_0_1_37(relative, (ROOT / relative).read_bytes()).decode("utf-8").replace("\r\n", "\n") + + def links(text_lf: str) -> str: """The Previous / Home / Next links of a page (the last ones).""" return list(MIGRATION.FOOTER.finditer(text_lf))[-1].group(0) @@ -45,7 +52,7 @@ def links(text_lf: str) -> str: def without(relative: Path, heading: str) -> str: """A live page without the section that starts at the heading (it runs to the page's links).""" - live = lf(ROOT / relative) + live = at_0_1_36(relative) start = live.index(heading) footer = list(MIGRATION.FOOTER.finditer(live))[-1].start() return live[:start].rstrip("\n") + "\n\n" + live[footer:] @@ -97,10 +104,10 @@ def test_the_design_note_is_linked(self) -> None: def test_the_migration_turns_the_0_1_24_pages_into_the_live_pages(self) -> None: # The frozen texts are exactly the template's sections, at the place the template has them. - self.assertEqual(MIGRATION.add_section(page_0_1_24(), SECTION), lf(ROOT / PAGE)) + self.assertEqual(MIGRATION.add_section(page_0_1_24(), SECTION), at_0_1_36(PAGE)) old = troubleshooting_0_1_24() self.assertFalse(old.endswith(links(old))) # the links were in the middle - self.assertEqual(MIGRATION.add_section(old, ENTRY), lf(ROOT / TROUBLESHOOTING)) + self.assertEqual(MIGRATION.add_section(old, ENTRY), at_0_1_36(TROUBLESHOOTING)) def test_every_documentation_page_ends_with_its_links(self) -> None: for path in sorted((ROOT / ".tools/docs").glob("*.md")): @@ -157,8 +164,8 @@ def test_the_template_pages_of_0_1_25_become_the_live_pages_and_a_second_run_cha self.put(PAGE, page_0_1_24()) self.put(TROUBLESHOOTING, troubleshooting_0_1_24()) log = self.run_migration() - self.assertEqual(lf(self.repo / PAGE), lf(ROOT / PAGE)) - self.assertEqual(lf(self.repo / TROUBLESHOOTING), lf(ROOT / TROUBLESHOOTING)) + self.assertEqual(lf(self.repo / PAGE), at_0_1_36(PAGE)) + self.assertEqual(lf(self.repo / TROUBLESHOOTING), at_0_1_36(TROUBLESHOOTING)) self.assertIn("2 file(s) changed", log) self.assertIn("no repository changes were required", self.run_migration()) diff --git a/tests/test_template_sync_0_1_35.py b/tests/test_template_sync_0_1_35.py index 4cd45b6..d95a0e8 100644 --- a/tests/test_template_sync_0_1_35.py +++ b/tests/test_template_sync_0_1_35.py @@ -140,7 +140,8 @@ def test_the_links_of_the_changed_pages_resolve(self) -> None: page = ((ROOT / relative).parent / target).resolve() if target else ROOT / relative self.assertTrue(page.exists()) if anchor: - headings = [slug(line.lstrip("#")) for line in lf(page).splitlines() if line.startswith("#")] + page_text = before_0_1_36(page.relative_to(ROOT), page.read_bytes()).decode("utf-8").replace("\r\n", "\n") + headings = [slug(line.lstrip("#")) for line in page_text.splitlines() if line.startswith("#")] self.assertIn(anchor, headings) diff --git a/tests/test_template_sync_0_1_36.py b/tests/test_template_sync_0_1_36.py index 6ebe41e..cde0e1e 100644 --- a/tests/test_template_sync_0_1_36.py +++ b/tests/test_template_sync_0_1_36.py @@ -15,6 +15,7 @@ from types import ModuleType from _v0_1_36 import before_0_1_36, template_bytes +from _v0_1_37 import before_0_1_37 ROOT = Path(__file__).resolve().parents[1] @@ -38,6 +39,11 @@ def lf(path: Path) -> str: return path.read_bytes().decode("utf-8").replace("\r\n", "\n") +def at_0_1_36(relative: Path) -> bytes: + """The 0.1.36 template file: the live file without the 0.1.37 change (tests/_v0_1_37.py).""" + return before_0_1_37(relative, (ROOT / relative).read_bytes()) + + 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)) @@ -76,7 +82,7 @@ def test_the_live_files_are_the_0_1_35_files_migrated(self) -> None: 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, at_0_1_36(relative).decode("utf-8")) def test_no_user_page_links_use_cases_or_calls_the_plugins_experimental(self) -> None: for path in user_pages(): @@ -91,7 +97,7 @@ def test_no_user_page_links_use_cases_or_calls_the_plugins_experimental(self) -> 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)): + for target in re.findall(r"\]\(([^)#\s]+)(?:#[^)]*)?\)", at_0_1_36(relative).decode("utf-8")): if "://" in target: continue with self.subTest(file=str(relative), target=target): @@ -124,7 +130,7 @@ def assert_template_state(self) -> None: 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()) + self.assertEqual((self.repo / relative).read_bytes().replace(b"\r\n", b"\n"), at_0_1_36(relative)) def test_an_app_of_0_1_35_gets_the_template_files_and_a_second_run_changes_nothing(self) -> None: log = self.run_migration() diff --git a/tests/test_template_sync_token_integration.py b/tests/test_template_sync_token_integration.py index eb05f2e..099aaca 100644 --- a/tests/test_template_sync_token_integration.py +++ b/tests/test_template_sync_token_integration.py @@ -5,6 +5,8 @@ import unittest from pathlib import Path +from _v0_1_37 import before_0_1_37 + REPO_ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ( @@ -142,7 +144,7 @@ def test_repository_template_files_match_migration_resources(self): Path(".tools/docs/template_synchronization.md"), ): self.assertEqual( - (REPO_ROOT / relative).read_bytes(), + before_0_1_37(relative, (REPO_ROOT / relative).read_bytes()), (resource_root / relative).read_bytes(), relative, ) From daafca94134e5f36f6b4515cc2a853ce00914816 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 14:34:10 +0000 Subject: [PATCH 12/12] Tests of the 0.1.37 migration Resources are the live guides and differ from the frozen 0.1.36 copies; a 0.1.36 app reaches the live guides (LF and CRLF kept) and a second run changes nothing; a customised guide is SKIPPED; external_code_upload.md with the app's package name; missing files are not created; a file that is not text is kept; sync.py from 0.1.36 and the chain from 0.1.35. Also checks the sections the website wants in the critical guides, the system sections of install.md, the tools guide as an entry point and the sync guide's footer. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP --- tests/test_template_sync_0_1_37.py | 237 +++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 tests/test_template_sync_0_1_37.py diff --git a/tests/test_template_sync_0_1_37.py b/tests/test_template_sync_0_1_37.py new file mode 100644 index 0000000..ae11571 --- /dev/null +++ b/tests/test_template_sync_0_1_37.py @@ -0,0 +1,237 @@ +"""Tests of the 0.1.37 migration: the rewritten user guides replace the 0.1.36 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_36 import before_0_1_36 + + +ROOT = Path(__file__).resolve().parents[1] +MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_36_to_v0_1_37.py" +SYNC_PATH = ROOT / ".template_sync/sync.py" +DOCS = ROOT / ".tools/docs" +# The guides a first-time reader follows to the end: the website checks that each has these level-2 headings. +CRITICAL = ("install.md", "initialise_repository.md", "notebook_requirements.md", "notebook_upload.md", "executable_creation.md") +WANTED = (("what you need", "before you start"), ("check that it worked",), ("if something does not work",)) + + +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_37") + + +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.36 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\.(3[7-9]|[4-9][0-9])\b") + self.assertIn(" - from: 0.1.36\n to: 0.1.37\n script: migrations/v0_1_36_to_v0_1_37.py\n", text) + + def test_chains_from_older_versions_reach_0_1_37(self) -> None: + sync = load(SYNC_PATH, "sync_for_0_1_37") + manifest = sync.parse_manifest(ROOT / ".template_sync/manifest.yaml") + for start in ("0.0.0", "0.1.16", "0.1.35", "0.1.36"): + chain = sync.resolve_migration_chain(manifest["migrations"], start, "0.1.37") + self.assertEqual(chain[-1]["to"], "0.1.37", start) + + def test_the_design_note_exists_and_is_not_in_the_docs_index(self) -> None: + self.assertIn(".tools/docs/migration_0_1_37.md", MIGRATION_PATH.read_text(encoding="utf-8")) + self.assertTrue((DOCS / "migration_0_1_37.md").is_file()) + self.assertNotIn("migration_0_1_37.md", lf(DOCS / "README.md")) + + def test_the_resources_are_the_live_guides_and_the_0_1_36_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_36_guides(self) -> None: + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + self.assertEqual(before_0_1_36(relative, live(relative)), before_0_1_36(relative, previous(relative))) + + def test_the_critical_guides_have_the_sections_the_website_checks(self) -> None: + for name in CRITICAL: + headings = [line[3:].strip().lower() for line in lf(DOCS / name).splitlines() if line.startswith("## ")] + for options in WANTED: + with self.subTest(guide=name, section=options[0]): + self.assertTrue(any(h in options for h in headings)) + + def test_install_keeps_the_system_sections_the_website_cuts(self) -> None: + headings = [line[3:].strip() for line in lf(DOCS / "install.md").splitlines() if line.startswith("## ")] + for heading in ("Install on Windows", "Install on a Mac", "Install on Linux", "Uninstall an app"): + self.assertIn(heading, headings) + + def test_the_tools_guide_is_an_entry_point(self) -> None: + text = lf(DOCS / "tools_bridge.md") + self.assertIn("](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/)", text) + self.assertNotIn("This page covers", text) + self.assertNotIn("Move the pin", text) + self.assertIn("LC_TOOLS_PIN", text) + + def test_the_footer_of_the_sync_guide_follows_the_docs_index(self) -> None: + index = re.findall(r"\]\(([a-z_0-9]+\.md)\)", lf(DOCS / "README.md")) + position = index.index("template_synchronization.md") + text = lf(DOCS / "template_synchronization.md") + self.assertIn(f"[← Previous]({index[position - 1]})", text) + self.assertIn(f"[Next →]({index[position + 1]})", text) + + def test_the_relative_links_of_the_guides_resolve(self) -> None: + for relative in MIGRATION.FILES: + 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_37_")) + 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_36_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_and_the_others_change(self) -> None: + relative = Path(".tools/docs/troubleshooting.md") + own = previous(relative) + b"\n## Our own problem\n\nOur own fix.\n" + page = self.put(relative, own) + log = self.run_migration() + self.assertIn(f"{relative}: SKIPPED: customised (not the 0.1.36 template file)", log) + self.assertEqual(page.read_bytes(), own) + self.assertIn(f"done: {len(MIGRATION.FILES) - 1} file(s) changed", log) + + def test_the_external_code_guide_with_the_package_name(self) -> None: + relative = MIGRATION.EXTERNAL_CODE_DOC + self.assertIn("PYTHON_PROJ_NAME", previous(relative).decode("utf-8")) + page = self.put(relative, previous(relative).replace(b"PYTHON_PROJ_NAME", b"celltools")) + log = self.run_migration() + self.assertIn(f"{relative}: updated: replaced by the 0.1.37 page (with the package name celltools)", log) + self.assertEqual(page.read_bytes(), live(relative).replace(b"PYTHON_PROJ_NAME", b"celltools")) + again = self.run_migration() + self.assertIn(f"{relative}: unchanged: already up to date", again) + mixed = previous(relative).replace(b"PYTHON_PROJ_NAME", b"celltools", 1).replace(b"PYTHON_PROJ_NAME", b"other") + self.put(relative, mixed) + self.assertIn(f"{relative}: SKIPPED", self.run_migration()) + + 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/install.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.37 (later templates add migrations). + manifest.write_text(with_version(manifest.read_text(encoding="utf-8"), "0.1.37"), encoding="utf-8") + command = [sys.executable, str(self.repo / ".template_sync/sync.py"), "--from-version", start, "--to-version", "0.1.37", "--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_36(self) -> None: + result = self.sync("0.1.36") + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("[migration 0.1.37]", result.stdout) + self.assert_template_state() + again = self.sync("0.1.36") + self.assertIn("[migration 0.1.37] done: no repository changes were required", again.stdout) + + def test_the_sync_chain_from_0_1_35_reaches_the_live_guides(self) -> None: + """0.1.36 edits the 0.1.35 tools guide, then 0.1.37 replaces it.""" + relative = Path(".tools/docs/tools_bridge.md") + self.put(relative, before_0_1_36(relative, previous(relative))) + self.assertNotEqual((self.repo / relative).read_bytes(), previous(relative)) + result = self.sync("0.1.35") + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertEqual((self.repo / relative).read_bytes(), live(relative), result.stdout) + + +if __name__ == "__main__": + unittest.main()