Foundation I: make download, installation and update recovery clear
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Feature
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- html, javascript, swift
- Domain
- desktop, documentation, release
Research direction
Start with section 6 of docs/mac-foundation.md, then read WorkbenchUpdates.swift, WorkbenchUpdateDriver.swift, site/index.html, site/release.mjs, docs/updating.md and the existing release/installer tests. Implement the decided download, installation and update-recovery scope without replacing Sparkle or the signed release workflow. Done means meeting I1/I2/U2 with the specified fresh-install and signed-update evidence, including failure, retry and data-preservation checks.
Written by the indexing model from the issue text.
Description
Complete the customer journey from the public Workbench download to a correctly installed app, and make installation/update refusal understandable without losing the working app or saved material. This closes package I of the focused Mac foundation under #7. It does not replace Sparkle or the signed release workflow.
Decided scope
- Keep the signed/notarized ZIP, the existing Workbench/Sparkle update owner and current release pipeline. Consume merged #271's one-action update UI.
- Align the landing/download/help copy with released hardware/OS requirements, version and edition. First install uses the person's home Applications folder; replacement keeps the existing Applications location, including
/Applications. Give exact Finder directions without requiring Terminal or knowledge of~. Do not silently move/delete duplicate installations or migrate Preview data into Stable. - Correct unverified setup-duration promises. The primary ordinary update is Update to [version]; Settings remains the place for manual checks/preferences. A first non-speech job must not trigger model setup.
- Known Downloads/read-only/translocation refusal gives quit, move, reopen and retry instructions using the existing surface. Authorization refusal leaves the prior app/data usable and offers a deliberate retry/help route. Distinguish known network, disk, signature and compatibility errors; unknown failure is not proof of corporate policy. No authorization loops or security-setting bypass.
- Existing busy deferral, save-before-restart, retained user update preferences, exact edition/signing identity and previous-package recovery remain authoritative. Failed/cancelled download or replacement never claims the installed version changed; post-relaunch verification establishes success. Binary rollback must respect storage compatibility.
Acceptance
I1/I2/U2 in docs/mac-foundation.md are required before calling this complete. Observe a real browser-downloaded install on a suitable fresh account/environment, open the actual installed edition, perform the chosen useful job and reopen its saved result. Separately verify an actual old-to-new signed Sparkle update, busy/failed-save deferral, refusal/cancellation/retry and preserved data/preferences. Tests cover typed failure/unknown cases; native evidence covers applicable real location/authorization/relaunch behavior. No account-free first-use claim is established by an already trusted developer Mac.
Record source, edition, build, archive identity, environment and exact limits in #7's existing release evidence. Older #134 update evidence is valuable but not automatic acceptance of #271 or a newer candidate. #2 is contributor fresh-clone setup and remains separate. #15 owns speech download/first-use; #165 owns manual copy/paste; #282 owns the small receipt gate, not this UI implementation.
Implementation starting points: WorkbenchUpdates.swift, WorkbenchUpdateDriver.swift, site/index.html, site/release.mjs, docs/updating.md, existing release/installer tests. Layout and error factoring remain flexible. No custom installer, DMG migration, new settings section, background monitor, account or telemetry.
Specification and evidence: docs/mac-foundation.md section 6 and docs/research/mac-foundation-2026-10.md coverage audit. This issue is build-ready scope, not a claim the changed experience is implemented or natively accepted.
- Dominant language
- Swift
- Stars
- 0
- Forks
- 1
- Avg merge
- 8h 5m
- Merged PRs (30d)
- 215
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from Ship-Work/workbench
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
Maintainers usually reply within 1 day
-
documentation good first issue help wanted
Difficulty 2/5 Half a day Newbie friendliness 74/100
Ship-Work/workbench#29 · 1 comment ·
Maintainers usually reply within 1 day
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 55/100
Maintainers usually reply within 1 day
All issues in Ship-Work/workbench
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
raullenchai/Rapid-MLX#4889 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
iOS-2026
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
mozilla-mobile/firefox-ios#36150 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 83/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
openwatersio/slackwater-ios#736 ·
Maintainers usually reply within 1 day