The build passed. The package existed. The release still had a first-boot problem.
That sequence is uncomfortable because each earlier signal looked reassuring. A compiler can finish. A packaging job can upload a file. A smoke test can launch the application in the environment where the build ran. Yet a user installing that artifact into a fresh profile may still be unable to create the data the application exists to protect.
A green build tells us the build path succeeded. It does not tell us the packaged app works with a real first-run state.
The first launch is a different test boundary
WorldScript Studio’s v1.28.7-to-v1.28.8 release history includes an AppImage persisted-state first-boot failure. The lesson is not that Linux packaging is inherently unreliable. It is that “the app started” and “a first-time user can persist work” are different assertions.
The user’s first session begins with the profile the product creates, not the developer’s already-populated workspace. That profile may require the application to create a directory, initialize storage, write a marker, migrate a schema, and then reopen the result. A bundle that launches but cannot complete that path is still broken for the user.
Qualify the artifact in a fresh profile
A useful first-boot protocol needs more than a checklist label. It should name the exact artifact, the clean profile, the setup steps, the expected state transitions, and the evidence to save.
For a desktop package, a minimal qualification might include:
- identify the artifact by filename and digest;
- start with a new profile or installation state;
- launch the packaged application;
- create or import a small project;
- make a change and wait for the durable save;
- close and relaunch;
- verify the data is still present;
- capture logs and resulting files as evidence.
The specific expected behavior depends on the product, but the key is repeatability. “Fresh install passed” without saying which package and which profile is not enough information for someone else to reproduce.
Separate build, package, and persisted-state evidence
A release has several evidence planes: source correctness, exact pull request checks, resulting main, build, packaged runtime, persisted state, tag-time jobs, and publication. Each can be green or red independently.
A test against a development build does not prove the downloaded artifact behaves identically. A packaged launch does not prove data survives a restart. A successful first save does not prove a pre-existing profile migrates safely. The evidence should say which plane it covers.
Later, PR #908 added a specific permissions correction for literal dot-files on Linux and macOS Tauri. That is a source change tied to a permission boundary; it does not erase the historical first-boot incident, and it is not by itself proof that a release artifact passed every first-boot scenario.
Turn the failure into a durable protocol
The strongest response to an incident is not just “we retested it.” It is to make the test identity and expected outcome repeatable. Record the package digest, host platform, profile state, steps, expected result, actual result, and terminal evidence. If a gate is still manual, say who watches it and what happens if it fails.
That precision prevents a passing result from migrating to the wrong package or release. It also lets future maintainers tell whether a test was rerun against the artifact users received or against a convenient equivalent.
A build is a necessary milestone. The first boot is a user journey. Release confidence improves when the exact package completes that journey with a clean profile and leaves verifiable persisted state behind.
Continue reading
Next: The Tag Must Not Be Your First Real Build moves the qualification point earlier in the release sequence.
Related: One React/Vite Product Across PWA and Tauri examines why desktop and browser packaging need their own evidence.
Practical extension: a first-boot qualification matrix
“Fresh install” is not one test. At minimum, qualify the exact packaged artifact across these starting conditions:
| Starting condition | What it reveals |
|---|---|
| New user profile, online | first-run defaults and initial network assumptions |
| New profile, offline | hidden download or service dependency |
| Existing profile with prior data | migration and compatibility behavior |
| Storage permission denied or unavailable | error handling and preservation |
| Upgrade from the previous supported release | migration of real user state |
Bind each result to the artifact digest, operating system, architecture, profile condition, and test run. A successful browser build or a source-level test is useful evidence, but neither proves a native installer starts with the permissions and files it actually receives. If launch fails, preserve logs and user data before trying cleanup; do not make “delete the profile” the first diagnostic action.
Use separate claims for built, packaged, installed, launched, and exercised. That vocabulary lets a release note say exactly what happened. For browser storage, include quota and eviction behavior in the first-run and recovery story rather than treating the origin database as a guaranteed backup; MDN documents those limits.
Top comments (0)