Skip to content

Document the first-launch OS warnings in the tutorial and README - #95

Merged
AlexisJanin merged 2 commits into
mainfrom
issue-94-first-launch-docs
Aug 28, 2026
Merged

Document the first-launch OS warnings in the tutorial and README#95
AlexisJanin merged 2 commits into
mainfrom
issue-94-first-launch-docs

Conversation

@AlexisJanin

Copy link
Copy Markdown
Collaborator

Closes #94.

The standalone bundles are not code-signed, so every platform interrupts the very first launch. Those workarounds lived only in the GitHub release bodies, so anyone reaching the project through the repository hit a blocked launch with no documented way past it.

Wording is lifted from the tested v1.1.0 release body rather than rewritten, as the issue asked.

docs/user_guide/tutorial.md — primary target

The issue asked for a "First launch" subsection under installation, but the tutorial has no installation section — it opens at Launching the Application already assuming an unzipped bundle. So the new ## First launch sits inside that section, immediately before Starting the App, which is where it falls chronologically. No download table or install instructions were added: this file ships as the PDF inside the bundle, so its reader has already downloaded.

  • ### Windows — first-launch elevation (right-click → Run as administrator) and the SmartScreen unknown-publisher warning, with the one-time / survives-reboot note.
  • ### macOS (Apple Silicon)xattr -d com.apple.quarantine on the .zip before unzipping, the browser auto-unzip heads-up, and the no-Intel-build pointer to PyPI.
  • ### Linux — unzip + chmod +x.

Two smaller edits in Starting the App:

  • "double-click it" directly contradicted the Windows elevation step, so it now points at First launch for the first run.
  • Added how to close the app (it runs in the terminal window that opened with it), which the issue listed but had no other home.

README.md — shorter form

The same instructions in a collapsible <details> block under the pre-built download table: three per-platform bullets with the exact commands, plus the closing-the-app line. 11 lines.

Collapsible rather than inline because README readers mostly install from PyPI or source, while bundle users are the ones who read the tutorial — this keeps the page self-sufficient for a downloaded bundle without flooding it. The content is still greppable and GitHub-searchable inside <details>.

The block is deliberately README-only: build_pdf.sh feeds tutorial.md to pandoc, and raw HTML is dropped on the LaTeX path, so a <details> there would vanish from the bundled PDF.

Verification

  • The issue's own check — grep -E "SmartScreen|quarantine|Run anyway" — returned nothing on either file before; now 3 hits in tutorial.md, 2 in README.md.
  • pandoc docs/user_guide/tutorial.md -t html parses with no warnings, and the new [First launch](#first-launch) cross-reference resolves (id="first-launch" is generated as expected), so the link works in the PDF.
  • tests/plot_types/test_plot_type_is_documented.py scans tutorial.md headings for plot-type names; it asserts presence, so the new headings cannot affect it.

Acceptance criteria

  • A user following only README.md can get a downloaded bundle running on Windows, macOS and Linux without consulting a release page.
  • The same instructions are in tutorial.md, so the bundled PDF carries them from the next release onward.

Not in scope

  • The committed ClinicalScope_UserGuide.pdf is untouched — it is rebuilt once per release (RELEASING.md step 1), so it will lag until then. The issue notes this is expected.
  • Why Windows needs elevation exactly once is still open, per the issue's own note.

🤖 Generated with Claude Code

The standalone bundles are not code-signed, so every platform interrupts
the first launch. Until now those workarounds existed only in the body of
the GitHub release pages, so anyone arriving through the repository hit a
blocked launch with nothing to go on.

tutorial.md gains a "First launch" section under Launching the
Application, covering Windows elevation + SmartScreen, macOS quarantine
stripping, and the Linux chmod, plus how to stop the app. It is the
primary target: it ships as the PDF inside every bundle.

README.md gains the same instructions in a collapsible <details> block,
so it stays self-sufficient for a downloaded bundle without flooding a
page whose readers mostly install from PyPI or source.

Wording is lifted from the tested v1.1.0 release body.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@AlexisJanin AlexisJanin self-assigned this Aug 28, 2026
@AlexisJanin AlexisJanin added the documentation Improvements or additions to documentation label Aug 28, 2026
@AlexisJanin
AlexisJanin merged commit 4944467 into main Aug 28, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document the first-launch OS warnings in the tutorial and README

2 participants