Document the first-launch OS warnings in the tutorial and README - #95
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 targetThe 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 launchsits 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.quarantineon the.zipbefore 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:
README.md— shorter formThe 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.shfeedstutorial.mdto pandoc, and raw HTML is dropped on the LaTeX path, so a<details>there would vanish from the bundled PDF.Verification
grep -E "SmartScreen|quarantine|Run anyway"— returned nothing on either file before; now 3 hits intutorial.md, 2 inREADME.md.pandoc docs/user_guide/tutorial.md -t htmlparses 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.pyscanstutorial.mdheadings for plot-type names; it asserts presence, so the new headings cannot affect it.Acceptance criteria
README.mdcan get a downloaded bundle running on Windows, macOS and Linux without consulting a release page.tutorial.md, so the bundled PDF carries them from the next release onward.Not in scope
ClinicalScope_UserGuide.pdfis untouched — it is rebuilt once per release (RELEASING.md step 1), so it will lag until then. The issue notes this is expected.🤖 Generated with Claude Code