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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .template_sync/manifest.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
template_version: 0.1.38
template_version: 0.1.39
migrations:
- from: 0.0.0
to: 0.0.1
Expand Down Expand Up @@ -120,3 +120,6 @@ migrations:
- from: 0.1.37
to: 0.1.38
script: migrations/v0_1_37_to_v0_1_38.py
- from: 0.1.38
to: 0.1.39
script: migrations/v0_1_38_to_v0_1_39.py
87 changes: 87 additions & 0 deletions .template_sync/migrations/v0_1_38_to_v0_1_39.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
"""Template 0.1.38 -> 0.1.39: the installer intros say that a release builds only the systems the app lists.

Design note: https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_39.md

before_getting_started.md and executable_creation.md said that a release builds installers for Windows, macOS and Linux. It builds only
the systems listed under `distribution.platforms` in labconstrictor-app.yaml (all of them when the list is missing); both intros now say so
and link the manifest guide.

What this changes in an app repository: each file in FILES is replaced by the 0.1.39 page when it is still the 0.1.38 template file
(compared with LF line endings; the file keeps its own line endings). A file the app changed itself stays as it is (SKIPPED, with a note of
what to change by hand). A missing file is not created, and nothing is deleted. The changes reach users with the app's next release.
"""
from __future__ import annotations

from pathlib import Path
from typing import Any


DOCS_URL = "https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_39.md"
TAG = "[migration 0.1.39]"
RESOURCE_ROOT = Path(__file__).resolve().parents[1] / "resources" / "v0_1_38_to_v0_1_39"
PREVIOUS_ROOT = RESOURCE_ROOT / "previous"

DOCS = Path(".tools/docs")

# Files replaced whole, only when they are the 0.1.38 template file (compared with LF line endings).
FILES = (DOCS / "before_getting_started.md", DOCS / "executable_creation.md")

# What to change by hand in a customised file (added to the SKIPPED note).
BY_HAND = (
"where the page says a release builds installers for Windows, macOS and Linux, add that it builds only the systems listed under "
"distribution.platforms in labconstrictor-app.yaml (link app_manifest.md#distribution-how-people-get-the-app)"
)


def log(message: str) -> None:
print(f"{TAG} {message}")


def lf_text(path: Path) -> str:
return path.read_bytes().decode("utf-8").replace("\r\n", "\n")


def replaced_file(relative: Path, text_lf: str) -> tuple[str, str]:
"""The 0.1.39 text of `relative` for the app's `text_lf`, and what was done. The text is unchanged when it is not the 0.1.38 template file."""
new = lf_text(RESOURCE_ROOT / relative)
previous = lf_text(PREVIOUS_ROOT / relative)
if text_lf == new:
return text_lf, "already up to date"
if text_lf == previous:
return new, "replaced by the 0.1.39 page"
return text_lf, (
"SKIPPED: customised (not the 0.1.38 template file), so it was left unchanged; compare it with the template's page. "
f"By hand: {BY_HAND}. See {DOCS_URL}"
)


def update(path: Path, relative: Path) -> str:
data = path.read_bytes().decode("utf-8")
newline = "\r\n" if "\r\n" in data else "\n"
original = data.replace("\r\n", "\n")
text, note = replaced_file(relative, original)
if text == original:
return note if note.startswith("SKIPPED") else f"unchanged: {note}"
path.write_bytes(text.replace("\n", newline).encode("utf-8"))
return f"updated: {note}"


def migrate(repo_root: Path, context: dict[str, Any]) -> None:
"""Apply the 0.1.39 documentation changes (idempotent, never raises for a customised file, creates and deletes nothing)."""
_ = context
changed = 0
for relative in FILES:
path = repo_root / relative
if not path.is_file():
log(f"{relative}: not present in this repository (nothing was created)")
continue
try:
status = update(path, relative)
except (OSError, UnicodeDecodeError) as exc:
status = f"SKIPPED: {exc}; left unchanged. See {DOCS_URL}"
changed += status.startswith("updated")
log(f"{relative}: {status}")
if changed:
log(f"done: {changed} file(s) changed. The changes reach users with the next release of the app.")
else:
log("done: no repository changes were required.")
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Before getting started with LabConstrictor

What LabConstrictor does, and what you need before you create your repository.

## LabConstrictor in a nutshell

LabConstrictor is a GitHub template repository that turns your Jupyter notebooks into a desktop app that people install with one installer. GitHub Actions workflows in your repository do the building.

### Easy configuration

A web form sets up your repository (name, version, description, images) and uploads your notebooks with their requirements. You do not edit the workflows yourself.

### Cross-platform installers

Publishing a release builds installers with [conda constructor](https://github.com/conda/constructor): Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app).

### Environment management

Each notebook comes with a `requirements.yaml` file that lists its packages. The workflows merge the requirements of all notebooks and fix every package version, so each installation of a release gets the same packages. Helper notebooks generate and check these files for you.

### Version control

The first cell of each notebook checks its version. The app's Welcome notebook shows when a newer version of a notebook exists and updates it.

### User-friendly experience

The installed app opens JupyterLab with a Welcome notebook that lists your notebooks. Code cells can be hidden and run with a play button, so a notebook looks like a simple app. Your repository can be public or private; a private repository cannot be listed in the App Centre.

### Offline usage

Once installed, the app runs without internet access, unless your notebooks need it.

## LabConstrictor requirements

- **A GitHub account**, to create your repository from the template.
- **Your Jupyter notebooks.**
- **A Python environment where your notebooks run without errors**, on your computer or in Google Colab. You use it to generate the requirements files. You can also write these files by hand.
- **A GitHub personal access token** (classic, with the **repo** scope), which the web forms use to open pull requests in your repository: see [Generate a GitHub personal access token](personal_access_token.md).
- **Optional: images** (logo, banner, header) to brand the installer: see [Customise the installer images](installer_images.md).

Next: [Create your repository](create_repository.md).


---

<div align="center">

← Previous &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[🏠 Home](README.md) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[Next →](create_repository.md)


</div>
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Create installer files

Publishing a GitHub release builds the installers of your app and attaches them to the release: Windows (`.exe`), macOS (`.pkg`, Apple Silicon and Intel) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app).

## What you need

- At least one notebook uploaded and merged: see [Add or update a notebook](notebook_upload.md).
- A version number for the release, in the form `MAJOR.MINOR.PATCH` (for example `0.0.1`).

## Check before you release

- **The systems you build for.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml`, or every system when that line is missing: see [`distribution` in Describe your app](app_manifest.md#distribution-how-people-get-the-app). Check that the list holds every system your app should run on.
- **Every workflow run is green.** Open the **Actions** tab of your repository. No workflow may still be running: a release started while another workflow runs may build from files that are about to change. The latest run of each workflow must have a green tick, not only have finished: a red cross means its changes, for example your notebook's requirements, did not make it into the repository ([how to read a run](workflow_status.md)).

## 1. Draft a new release

1. Go to your repository's main page.
2. Click **Releases** (in the right sidebar).
3. Click **Create a new release** and fill in:
- **Tag**: click **Create a new tag** and enter the version number, for example `0.0.1`. It must have the form `MAJOR.MINOR.PATCH` (`1.0.0`, `1.2.3`). A `v` in front (`v1.0.0`) also works: the installers are named with the version without it.
- **Release title**: for example `Initial release`.
- **Description** (optional): what is new in this release.

## 2. Publish the release

Click **Publish release**. This starts the workflow **Build Release Installers**. It sets the version in your repository's files, then builds one installer per system.

## Check that it worked

- In the **Actions** tab, the run of **Build Release Installers** has a green tick ([how to read a run](workflow_status.md)).
- Open your repository's **Releases** page and the release you published: its **Assets** list holds the installers, named `<App>-<version>-<System>` (for example `MyApp-0.0.1-Windows-x86_64.exe`).
- `.tools/docs/download_executable.md` in your repository now has download buttons for this release.

## If something does not work

- **The run stops at "check_placeholders.py", "Installers to build" or with conflicting package versions.** See [Troubleshooting repository setup](troubleshooting.md): each of these has its own section.
- **Another step failed.** Open the failed run and read the log of the red step ([how](workflow_status.md)). After you fix the problem, delete the release and its tag, then publish the release again.
- **An installer is missing for one system.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml` (all of them when it is not set): see [Describe your app for the App Centre](app_manifest.md).

## 3. After the release

- Try your installer yourself: [Install an app](install.md), then [Open and use an app](notebook_usage.md).
- List your app in the App Centre: [Describe your app for the App Centre](app_manifest.md), then [Submit your app](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/).
- Receive future template improvements as pull requests: [Keep your app up to date](template_synchronization.md).


---

<div align="center">

[← Previous](notebook_upload.md) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[🏠 Home](README.md) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[Next →](installer_images.md)


</div>
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Before getting started with LabConstrictor

What LabConstrictor does, and what you need before you create your repository.

## LabConstrictor in a nutshell

LabConstrictor is a GitHub template repository that turns your Jupyter notebooks into a desktop app that people install with one installer. GitHub Actions workflows in your repository do the building.

### Easy configuration

A web form sets up your repository (name, version, description, images) and uploads your notebooks with their requirements. You do not edit the workflows yourself.

### Cross-platform installers

Publishing a release builds installers for Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`) with [conda constructor](https://github.com/conda/constructor).

### Environment management

Each notebook comes with a `requirements.yaml` file that lists its packages. The workflows merge the requirements of all notebooks and fix every package version, so each installation of a release gets the same packages. Helper notebooks generate and check these files for you.

### Version control

The first cell of each notebook checks its version. The app's Welcome notebook shows when a newer version of a notebook exists and updates it.

### User-friendly experience

The installed app opens JupyterLab with a Welcome notebook that lists your notebooks. Code cells can be hidden and run with a play button, so a notebook looks like a simple app. Your repository can be public or private; a private repository cannot be listed in the App Centre.

### Offline usage

Once installed, the app runs without internet access, unless your notebooks need it.

## LabConstrictor requirements

- **A GitHub account**, to create your repository from the template.
- **Your Jupyter notebooks.**
- **A Python environment where your notebooks run without errors**, on your computer or in Google Colab. You use it to generate the requirements files. You can also write these files by hand.
- **A GitHub personal access token** (classic, with the **repo** scope), which the web forms use to open pull requests in your repository: see [Generate a GitHub personal access token](personal_access_token.md).
- **Optional: images** (logo, banner, header) to brand the installer: see [Customise the installer images](installer_images.md).

Next: [Create your repository](create_repository.md).


---

<div align="center">

← Previous &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[🏠 Home](README.md) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[Next →](create_repository.md)


</div>
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Create installer files

Publishing a GitHub release builds the installers of your app for Windows (`.exe`), macOS (`.pkg`, Apple Silicon and Intel) and Linux (`.sh`) and attaches them to the release.

## What you need

- At least one notebook uploaded and merged: see [Add or update a notebook](notebook_upload.md).
- A version number for the release, in the form `MAJOR.MINOR.PATCH` (for example `0.0.1`).

## Check before you release

- **The systems you build for.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml`, or every system when that line is missing: see [`distribution` in Describe your app](app_manifest.md#distribution-how-people-get-the-app). Check that the list holds every system your app should run on.
- **Every workflow run is green.** Open the **Actions** tab of your repository. No workflow may still be running: a release started while another workflow runs may build from files that are about to change. The latest run of each workflow must have a green tick, not only have finished: a red cross means its changes, for example your notebook's requirements, did not make it into the repository ([how to read a run](workflow_status.md)).

## 1. Draft a new release

1. Go to your repository's main page.
2. Click **Releases** (in the right sidebar).
3. Click **Create a new release** and fill in:
- **Tag**: click **Create a new tag** and enter the version number, for example `0.0.1`. It must have the form `MAJOR.MINOR.PATCH` (`1.0.0`, `1.2.3`). A `v` in front (`v1.0.0`) also works: the installers are named with the version without it.
- **Release title**: for example `Initial release`.
- **Description** (optional): what is new in this release.

## 2. Publish the release

Click **Publish release**. This starts the workflow **Build Release Installers**. It sets the version in your repository's files, then builds one installer per system.

## Check that it worked

- In the **Actions** tab, the run of **Build Release Installers** has a green tick ([how to read a run](workflow_status.md)).
- Open your repository's **Releases** page and the release you published: its **Assets** list holds the installers, named `<App>-<version>-<System>` (for example `MyApp-0.0.1-Windows-x86_64.exe`).
- `.tools/docs/download_executable.md` in your repository now has download buttons for this release.

## If something does not work

- **The run stops at "check_placeholders.py", "Installers to build" or with conflicting package versions.** See [Troubleshooting repository setup](troubleshooting.md): each of these has its own section.
- **Another step failed.** Open the failed run and read the log of the red step ([how](workflow_status.md)). After you fix the problem, delete the release and its tag, then publish the release again.
- **An installer is missing for one system.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml` (all of them when it is not set): see [Describe your app for the App Centre](app_manifest.md).

## 3. After the release

- Try your installer yourself: [Install an app](install.md), then [Open and use an app](notebook_usage.md).
- List your app in the App Centre: [Describe your app for the App Centre](app_manifest.md), then [Submit your app](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/).
- Receive future template improvements as pull requests: [Keep your app up to date](template_synchronization.md).


---

<div align="center">

[← Previous](notebook_upload.md) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[🏠 Home](README.md) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[Next →](installer_images.md)


</div>
2 changes: 1 addition & 1 deletion .tools/docs/before_getting_started.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ A web form sets up your repository (name, version, description, images) and uplo

### Cross-platform installers

Publishing a release builds installers for Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`) with [conda constructor](https://github.com/conda/constructor).
Publishing a release builds installers with [conda constructor](https://github.com/conda/constructor): Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app).

### Environment management

Expand Down
2 changes: 1 addition & 1 deletion .tools/docs/executable_creation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Create installer files

Publishing a GitHub release builds the installers of your app for Windows (`.exe`), macOS (`.pkg`, Apple Silicon and Intel) and Linux (`.sh`) and attaches them to the release.
Publishing a GitHub release builds the installers of your app and attaches them to the release: Windows (`.exe`), macOS (`.pkg`, Apple Silicon and Intel) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app).

## What you need

Expand Down
Loading
Loading