Document installing and running a released build - #208
Document installing and running a released build#208alex-rawlings-yyc wants to merge 18 commits into
Conversation
|
Warning Review limit reached
Next review available in: 4 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
📝 WalkthroughWalkthroughThe release process now includes Windows and Linux installation documentation, detailed release notes, optional Studio-version substitution, temporary release-body generation, and validation of published release content and required assets. ChangesRelease distribution
Estimated code review effort: 3 (Moderate) | ~20 minutes Suggested reviewers: Sequence Diagram(s)sequenceDiagram
participant Publisher
participant PublishWorkflow as GitHub Actions publish workflow
participant ReleaseBody as Temporary release-body file
participant DraftRelease as Draft release action
Publisher->>PublishWorkflow: Dispatch with optional studioVersion
PublishWorkflow->>ReleaseBody: Validate and substitute version placeholders
PublishWorkflow->>DraftRelease: Create draft release with generated body
sequenceDiagram
participant GitHubRelease as GitHub release event
participant VerifyWorkflow as GitHub Actions verify-release workflow
participant ReleasePayload as Release text and asset names
GitHubRelease->>VerifyWorkflow: Trigger on published or edited release
VerifyWorkflow->>ReleasePayload: Read release text and asset names
VerifyWorkflow->>VerifyWorkflow: Check placeholders, tag link, and required assets
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
4bc5b87 to
06fc303
Compare
imnasnainaec
left a comment
imnasnainaec
left a comment
There was a problem hiding this comment.
@imnasnainaec reviewed all commit messages and made 4 comments.
Reviewable status: 0 of 3 files reviewed, 4 unresolved discussions (waiting on alex-rawlings-yyc and jasonleenaylor).
README.md line 219 at r1 (raw file):
1. Make sure the versions in this repo are on the version number you want to release. If they are not, manually dispatch the [Bump Versions workflow](#bumping-version-without-publishing-a-release) or run the `bump-versions` npm script to set the versions to what you want to release on the branch you want to release from. 2. Update the Platform.Bible version line in `.github/assets/release-body.md` to the version this release was built and tested against. The Publish workflow records the exact `paranext-core` revision it built against in the workflow run's job summary.
🐛 Devin:
README.md:R219
Release checklist tells maintainers to update a line that no longer exists
The publishing checklist tells maintainers to update the Platform.Bible version line in the release body (README.md:219), but the rewritten release body no longer contains that line, so the step cannot be carried out as written and the real per-release edits get skipped.
Impact: Maintainers following the release steps will look for a line that isn't there and may publish a release whose application-build details were never refreshed.
Stale cross-reference between README publishing steps and the rewritten release body
The old .github/assets/release-body.md had Tested on Platform.Bible vX.Y.Z. Expected to be compatible with at least vX.Y.*., which is what README.md:219 refers to. The new body drops that line entirely; instead it carries an HTML maintainer note (.github/assets/release-body.md:9-12) saying to re-attach the matching application zip and update the version in the Assets line, and uses <version> placeholders at .github/assets/release-body.md:23 and :26. The README step should describe the new placeholders/maintainer note rather than the removed version line.
alex-rawlings-yyc
left a comment
alex-rawlings-yyc
left a comment
There was a problem hiding this comment.
@alex-rawlings-yyc made 4 comments.
Reviewable status: 0 of 3 files reviewed, 4 unresolved discussions (waiting on imnasnainaec and jasonleenaylor).
README.md line 219 at r1 (raw file):
Previously, imnasnainaec (D. Ror.) wrote…
🐛 Devin:
README.md:R219
Release checklist tells maintainers to update a line that no longer exists
The publishing checklist tells maintainers to update the Platform.Bible version line in the release body (
README.md:219), but the rewritten release body no longer contains that line, so the step cannot be carried out as written and the real per-release edits get skipped.
Impact: Maintainers following the release steps will look for a line that isn't there and may publish a release whose application-build details were never refreshed.Stale cross-reference between README publishing steps and the rewritten release body
The old
.github/assets/release-body.mdhadTested on Platform.Bible vX.Y.Z. Expected to be compatible with at least vX.Y.*., which is whatREADME.md:219refers to. The new body drops that line entirely; instead it carries an HTML maintainer note (.github/assets/release-body.md:9-12) saying to re-attach the matching application zip and update the version in the Assets line, and uses<version>placeholders at.github/assets/release-body.md:23and:26. The README step should describe the new placeholders/maintainer note rather than the removed version line.
Confirmed. That step pointed at the Tested on Platform.Bible vX.Y.Z line the
rewritten body dropped, so it's removed. The useful half — the job summary
recording the paranext-core revision — moves into the new attach step, where
it says which Studio build to pick.
.github/assets/release-body.md line 9 at r1 (raw file):
Previously, imnasnainaec (D. Ror.) wrote…
⛏️ Devin:
.github/assets/release-body.md:R9-12
Maintainer comment refers to an "Assets line" that doesn't exist as a version-bearing line
The hidden note says to "update the version in the Assets line below when it changes", but the body carries no concrete version — only
<version>placeholders in the download instructions (.github/assets/release-body.md:23,26). Either those placeholders should be filled in per release (in which case say so explicitly) or the note should be reworded, otherwise the instruction is ambiguous for the next maintainer.
Confirmed. There's no version-bearing Assets line; the only versions are the
<version> placeholders in the install steps. They're now filled in per
release, and the README says so. The note is cut back to the render check.
.github/assets/release-body.md line 21 at r1 (raw file):
Previously, imnasnainaec (D. Ror.) wrote…
🐛 Devin:
.github/assets/release-body.md:R21-24
Release body promises an application zip the Publish workflow never attaches
The release body states "Both files you need are in the Assets list below" and instructs downloading
Paratext.10.Studio.Setup.<version>-Windows.zip, but the Publish workflow only uploadsextension-repo/release/*(.github/workflows/publish.yml:107-108), which contains just the extension zip. The application build must be attached by hand each time — only the HTML maintainer comment at.github/assets/release-body.md:9-12records this, and it is invisible in the rendered release. If a maintainer forgets, the published release body will point testers at an asset that isn't there. Consider adding the manual attach step to the README publishing checklist as a visible step.
Confirmed. publish.yml:107-108 uploads only extension-repo/release/*, and
npm run package is build:production && zip-build dist release — the
extension zip is all that lands. Now a visible README step: attach the Studio
zip, fill in the placeholders, install both and confirm the tab renders before
publishing.
.github/assets/release-body.md line 25 at r1 (raw file):
Previously, imnasnainaec (D. Ror.) wrote…
⛏️ Devin:
.github/assets/release-body.md:R25-26
Release body step 2 refers to "the next step" but the folder is used two steps later
Step 2 says starting the app once "creates the folder used in the next step", but the next step (3) is downloading the extension zip; the folder is only used in step 4. INSTALL.md gets this right (
INSTALL.md:26-27points at step 3, which is the copy step). Minor wording fix: reference step 4 explicitly.
Confirmed, fixed — now reads "the folder used in step 4".
imnasnainaec
left a comment
imnasnainaec
left a comment
There was a problem hiding this comment.
@imnasnainaec reviewed all commit messages, made 2 comments, and resolved 3 discussions.
Reviewable status: 0 of 3 files reviewed, 2 unresolved discussions (waiting on alex-rawlings-yyc and jasonleenaylor).
.github/assets/release-body.md line 9 at r1 (raw file):
Previously, alex-rawlings-yyc (Alex Rawlings) wrote…
Confirmed. There's no version-bearing Assets line; the only versions are the
<version>placeholders in the install steps. They're now filled in per
release, and the README says so. The note is cut back to the render check.
⛏️ The "Maintainers" note is redundant with the README steps and could perhaps just be dropped here so it's not in the published code.
.github/assets/release-body.md line 24 at r2 (raw file):
Devin caution:
[...] the literal
<version>placeholders in the asset filenames reach the published release unless a maintainer edits them by hand. The README's new step 3 documents this manual step, but sinceomitBodyDuringUpdate: truealso means re-running the workflow won't refresh the body, a forgotten edit permanently ships instructions naming files that don't match the actual asset names. Consider substituting the version in the workflow (e.g.sedon the body file before the release action) so the instructions are always accurate.
b1e7899 to
428bfa4
Compare
alex-rawlings-yyc
left a comment
alex-rawlings-yyc
left a comment
There was a problem hiding this comment.
@alex-rawlings-yyc made 2 comments.
Reviewable status: 0 of 4 files reviewed, 2 unresolved discussions (waiting on imnasnainaec and jasonleenaylor).
.github/assets/release-body.md line 9 at r1 (raw file):
Previously, imnasnainaec (D. Ror.) wrote…
⛏️ The "Maintainers" note is redundant with the README steps and could perhaps just be dropped here so it's not in the published code.
Agreed, dropped. The attach step and render check are README steps 3 and 4.
.github/assets/release-body.md line 24 at r2 (raw file):
Previously, imnasnainaec (D. Ror.) wrote…
Devin caution:
[...] the literal
<version>placeholders in the asset filenames reach the published release unless a maintainer edits them by hand. The README's new step 3 documents this manual step, but sinceomitBodyDuringUpdate: truealso means re-running the workflow won't refresh the body, a forgotten edit permanently ships instructions naming files that don't match the actual asset names. Consider substituting the version in the workflow (e.g.sedon the body file before the release action) so the instructions are always accurate.
Confirmed, done. The workflow now fills interlinearizer_<version>.zip from
package.json before drafting the release, and fails if the placeholder is
missing. <Studio version> stays manual — separate build, README step 3.
imnasnainaec
left a comment
imnasnainaec
left a comment
There was a problem hiding this comment.
@imnasnainaec reviewed all commit messages, made 1 comment, and resolved 1 discussion.
Reviewable status: 0 of 4 files reviewed, 1 unresolved discussion (waiting on alex-rawlings-yyc and jasonleenaylor).
.github/assets/release-body.md line 24 at r2 (raw file):
Previously, alex-rawlings-yyc (Alex Rawlings) wrote…
Confirmed, done. The workflow now fills
interlinearizer_<version>.zipfrom
package.json before drafting the release, and fails if the placeholder is
missing.<Studio version>stays manual — separate build, README step 3.
⛏️ Could we add an automatic check in the publish workflow that the has been filled in?
alex-rawlings-yyc
left a comment
alex-rawlings-yyc
left a comment
There was a problem hiding this comment.
@alex-rawlings-yyc made 1 comment.
Reviewable status: 0 of 4 files reviewed, 1 unresolved discussion (waiting on imnasnainaec and jasonleenaylor).
.github/assets/release-body.md line 24 at r2 (raw file):
Previously, imnasnainaec (D. Ror.) wrote…
⛏️ Could we add an automatic check in the publish workflow that the has been filled in?
This job is what writes the <Studio version> placeholder — the Studio zip isn't attached until after the draft exists, so the placeholder is unfilled by construction and the guard would fail on every run.
Instead I've removed the need for the manual edit: an optional studioVersion dispatch input, substituted into the install steps the same way the extension version already is (and failing if that placeholder has gone missing). Leave it blank for today's behavior.
If you want a backstop for the blank case, an on: release: published job could fail when the body still says <Studio version> or no Paratext.10.Studio.Setup.*-Windows.zip is attached — the first point the check is meaningful, though it fires after the publish click rather than blocking it. Say the word and I'll add it.
imnasnainaec
left a comment
imnasnainaec
left a comment
There was a problem hiding this comment.
@imnasnainaec made 1 comment.
Reviewable status: 0 of 4 files reviewed, 1 unresolved discussion (waiting on alex-rawlings-yyc and jasonleenaylor).
.github/assets/release-body.md line 24 at r2 (raw file):
Previously, alex-rawlings-yyc (Alex Rawlings) wrote…
This job is what writes the
<Studio version>placeholder — the Studio zip isn't attached until after the draft exists, so the placeholder is unfilled by construction and the guard would fail on every run.Instead I've removed the need for the manual edit: an optional
studioVersiondispatch input, substituted into the install steps the same way the extension version already is (and failing if that placeholder has gone missing). Leave it blank for today's behavior.If you want a backstop for the blank case, an
on: release: publishedjob could fail when the body still says<Studio version>or noParatext.10.Studio.Setup.*-Windows.zipis attached — the first point the check is meaningful, though it fires after the publish click rather than blocking it. Say the word and I'll add it.
Let's do that.
alex-rawlings-yyc
left a comment
alex-rawlings-yyc
left a comment
There was a problem hiding this comment.
@alex-rawlings-yyc made 1 comment.
Reviewable status: 0 of 4 files reviewed, 1 unresolved discussion (waiting on imnasnainaec and jasonleenaylor).
.github/assets/release-body.md line 24 at r2 (raw file):
Previously, imnasnainaec (D. Ror.) wrote…
Let's do that.
Added — .github/workflows/verify-release.yml runs on release: published and fails when
the body still has its <Studio version> placeholder or no
Paratext.10.Studio.Setup.<version>-Windows.zip is attached. Both failures report in one
run, and the asset check lists what is attached.
It also runs on edited, so fixing a flagged release clears the failure, and it skips
drafts — their placeholders are meant to be unfilled until step 3. No checkout, no token:
everything it needs is in the release payload.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
|
Previously, imnasnainaec (D. Ror.) wrote…
Yep |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
imnasnainaec
left a comment
imnasnainaec
left a comment
There was a problem hiding this comment.
Four small suggestions: three on the new Verify Release workflow, one on a doc string this PR made stale. None blocking.
Add INSTALL.md, an end-user guide for getting the Interlinearizer into Platform.Bible without building it: install Platform.Bible, download the release zip, drop it unextracted into the installed-extensions folder, restart, then open it from the Scripture Editor's project menu. Covers first steps, updating, uninstalling, and troubleshooting. The extensions folder differs on Linux: the snap reads only ~/snap/platform-bible/common/app/installed-extensions, and a zip placed in ~/.platform.bible/installed-extensions is ignored without any warning, even though that folder exists and holds projects. Verified by installing the built zip into a Platform.Bible 0.5.0 snap and watching it unpack, load, and activate. Replace the template placeholders in the release body with real content, and record that 0.0.1 loads but does not render on v0.5.0: platform-bible-react's footnote editor evaluates Object.entries(usfmMarkers) at module scope, and usfmMarkers only entered platform-bible-utils (a host-supplied external) in March 2026, after v0.5.0 shipped. Point the README at INSTALL.md and note that publishing a release is what produces a download link testers can use without a GitHub account. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Releases now carry the Windows application build alongside the extension; public Platform.Bible v0.5.0 loads the extension but leaves its window blank.
The extension zip is the only asset the Publish workflow uploads, so the application build and the release body's version placeholders need a visible step rather than a hidden maintainer note.
The body is copied verbatim and never refreshed after the draft exists, so a missed hand edit permanently ships a literal `<version>`. The separately versioned Studio zip keeps a distinct `<Studio version>` placeholder for the one edit still required, and the maintainer note the README duplicated goes.
Substituting in place dirtied the tracked release body, so the Bump repo versions step failed whenever bumpRef was left blank.
The Studio build's version can only come from a dispatch input, since the workflow runs before that zip is attached by hand. Left blank, the release body keeps its placeholder for a maintainer to edit on the draft.
The Studio zip and the version the install steps name it by are attached and filled in by hand, so nothing can check them until the draft is published.
Also fixes the extensions folder (`.paratext-10-studio`, not `.platform.bible`) and reworks step 5 around Simple mode's project picker.
The Studio zips were checked but the extension zip was not, so a hand-made release could name a zip that was never attached. Also hoist the `<Studio version>` assertion out of the `studioVersion` branch, and point INSTALL.md step 1 at the release the reader came from rather than the newest one.
The install command's angle-bracket placeholders are shell redirection, so a paste fails; `--dangerous` skips snapd verification but does not grant unlimited system access; and only Linux app removal was documented.
`--dangerous` skips snapd's verification but leaves the snap's declared confinement intact, and nothing ever substitutes the file name's `<build>` placeholder, so the body now says both as the guide already does. Verify Release no longer reports an unfilled extension-zip placeholder a second time as a missing asset, and `USERPROFILE` joins the cspell word list.
An unfilled `<Studio version>` placeholder cannot match the file-name pattern, so the check reported a missing name per platform on top of the accurate placeholder error.
imnasnainaec
left a comment
imnasnainaec
left a comment
There was a problem hiding this comment.
@imnasnainaec reviewed 2 files and all commit messages, made 1 comment, and resolved 1 discussion.
Reviewable status: 2 of 6 files reviewed, 5 unresolved discussions (waiting on alex-rawlings-yyc and jasonleenaylor).
README.md line 261 at r8 (raw file):
⛏️ Paragraph 3 is unwieldy for step-by-step instructions. How's this for a reordering?
- Download matching Windows and Linux zips of Paratext 10 Studio setup. Studio builds are published on the
paratext-10-studioreleases page, a private repo — that link 404s unless your GitHub account has been granted access.
- Attach the Paratext 10 Studio builds to the new draft release, both
Paratext.10.Studio.Setup.<Studio version>-Windows.zipandParatext.10.Studio.Setup.<Studio version>-Linux.zip. If you leftstudioVersionblank in step 2, also replace<Studio version>in the release body's install steps with the version of the zips you attached. The body has to name the zips you actually attached. (The workflow automatically attaches the extension zip and fills in its version.)
(and adjuest the numbering below)
A body naming no Studio zip is a warning rather than an error, so the check survives the application build moving to its own releases; a concurrency group keeps superseded `edited` runs from failing against an already-fixed body.
8160106 to
007d6bb
Compare
alex-rawlings-yyc
left a comment
alex-rawlings-yyc
left a comment
There was a problem hiding this comment.
@alex-rawlings-yyc made 5 comments.
Reviewable status: 2 of 6 files reviewed, 5 unresolved discussions (waiting on imnasnainaec and jasonleenaylor).
README.md line 261 at r8 (raw file):
Previously, imnasnainaec (D. Ror.) wrote…
⛏️ Paragraph 3 is unwieldy for step-by-step instructions. How's this for a reordering?
- Download matching Windows and Linux zips of Paratext 10 Studio setup. Studio builds are published on the
paratext-10-studioreleases page, a private repo — that link 404s unless your GitHub account has been granted access.
- Attach the Paratext 10 Studio builds to the new draft release, both
Paratext.10.Studio.Setup.<Studio version>-Windows.zipandParatext.10.Studio.Setup.<Studio version>-Linux.zip. If you leftstudioVersionblank in step 2, also replace<Studio version>in the release body's install steps with the version of the zips you attached. The body has to name the zips you actually attached. (The workflow automatically attaches the extension zip and fills in its version.)(and adjuest the numbering below)
Good call, split as suggested with the numbering below adjusted. One change from your wording: I kept the sentence about the Publish job summary recording the paranext-core revision, moved into the new step 3 — it's the only place that says how to tell which Studio build is the matching one, so "matching" loses its meaning without it.
imnasnainaec
left a comment
imnasnainaec
left a comment
There was a problem hiding this comment.
Two more, both about the release body's <Studio version> placeholder outliving the attached application build. Neither is blocking.
The line keeps version guidance once the temporary Studio zips go away, and keeps a `<Studio version>` placeholder in the body, so the publish guard no longer contradicts Verify Release's warning about a body that names no Studio zip.
alex-rawlings-yyc
left a comment
alex-rawlings-yyc
left a comment
There was a problem hiding this comment.
@alex-rawlings-yyc made 2 comments.
Reviewable status: 2 of 7 files reviewed, 7 unresolved discussions (waiting on imnasnainaec and jasonleenaylor).
2 participants
Adds
INSTALL.md, a tester-facing guide that needs no development tools, a shortpointer to it from the README, and a rewritten
.github/assets/release-body.mdsoevery release carries the same instructions.
Testers install Paratext 10 Studio — the application built on Platform.Bible —
from a build attached to each release, rather than from the Snap Store or the
paranext-core releases page. Public Platform.Bible v0.5.0 activates the extension
but leaves its WebView blank, so sending testers there wastes their time.
Windows only for now, since that is the only application build available. A
Linux build has been requested; there is no macOS build. The docs say so up front
instead of letting other platforms get halfway through.
Notes for review:
"tested against" it — nobody has confirmed the extension renders on Paratext 10
Studio 0.4.0-alpha.0 yet. Worth upgrading once a Windows tester confirms (four
places: two in
INSTALL.md, one each in the README and release body).%USERPROFILE%\.platform.bible\installed-extensionsunder Paratext 10 Studio:
PRODUCT_FOLDER_NAMEis a hard-coded constant inparanext-core, not derived from branding. The docs explain the mismatched name so
it does not look like a mistake to testers.
bodyFilewhen creating a release(
omitBodyDuringUpdate: true), so the existing draft v0.0.1 body still has to beupdated by hand. Merging this only fixes future releases.
Part of #203.
This change is
Summary by CodeRabbit
Documentation
Release Improvements