104 lines
10 KiB
Markdown
104 lines
10 KiB
Markdown
---
|
||
type: postmortem
|
||
project: Migration to fully VSCode-supported builds&debugging
|
||
asana: https://app.asana.com/1/137249556945/project/1203301625297703/task/1209808486380252
|
||
postmortem_task: https://app.asana.com/1/137249556945/project/1203301625297703/task/1219573444990290
|
||
started: 2025-05-27
|
||
completed: 2026-10-16
|
||
postmortem_date: 2026-10-20
|
||
dri: Alex M
|
||
---
|
||
|
||
# Postmortem: Migration to fully VSCode-supported builds&debugging
|
||
|
||
**For what:** [Migration to fully VSCode-supported builds&debugging](https://app.asana.com/1/137249556945/project/1203301625297703/task/1209808486380252)
|
||
**Started:** 2025-05-27 (task created 2025-03-27) · **Closed:** 2026-10-16 · **DRI:** Alex M
|
||
**Zoom link:**
|
||
|
||
Related notes: [[projects/vscode-migration/vscode-migration]] · [[projects/vscode-migration/findings]] · [[projects/vscode-migration/tech-design-spm-browser-package]] · [[projects/vscode-migration/tech-design-xcode-build-server]] · [[projects/vscode-migration/modularization-roadmap]]
|
||
|
||
## Did the project accomplish its success criteria?
|
||
|
||
Yes. The full development cycle (build, run, test, debug) for the Apple browsers now works from VSCode/Cursor, on macOS and iOS, without changing the Xcode projects.
|
||
|
||
| Objective | Result |
|
||
|---|---|
|
||
| Drop storyboards/xibs | ✅ macOS app is 100% code-initialized |
|
||
| Organize code by target; share code through dependencies instead of multi-target membership | ✅ per-target flags (`SPARKLE`/`APPSTORE`/…) dropped, app target file membership cleaned up (phases A, B, C-a), ObjC/C moved to packages |
|
||
| Make most of the project SPM-compatible | ✅ partly: `#bundle` localization + lint rule, `NSImage(resource:)` assets, sandbox UI tests. Making the browser code a Swift package was dropped |
|
||
| VSCode environment for development and debugging | ✅ through an Xcode build server; opt-in [instruction](https://app.asana.com/1/137249556945/project/1202500774821704/task/1209678170937083) only, not adopted by the team |
|
||
|
||
The refactoring steps were needed on their own, and reviewers agreed on that ("happy about the improvements made so far"). Only the last, and one of the shortest, steps (VSCode support in the repo) wasn't adopted.
|
||
|
||
The SPM build-time gains in the project description (−24% to −30% clean build) didn't happen, because the package step was dropped.
|
||
|
||
## What went well that we can repeat in the future?
|
||
|
||
- The prerequisites shipped as small, separate refactors (storyboards, target flags, membership, assets, strings). Each one improved the codebase on its own.
|
||
- Tech design reviews worked. The 2025 module-conversion TD was approved after its questions were answered. Its 2026 follow-up (the browser code as a Swift package) got specific objections, and a narrower, opt-in build-server TD followed the same day it was closed.
|
||
- Dropping the CoreData code-model migration once Xcode 27's swift-build built the models as they are. That removed the riskiest change people raised on Sep 29.
|
||
- I use the setup every day. On top of convenience compared to Xcode, it opens up remote debugging on older macOS versions (VMs).
|
||
|
||
## What didn't go well that was avoidable, and how can we prevent those things in the future?
|
||
|
||
- **Incident on macOS 12.** [macOS browser 1.211.0 crashed on macOS 12 when saving credentials](https://app.asana.com/1/137249556945/project/1210995391161861/task/1219405566971347) (2026-10-12; 1h35m user impact, rollout stopped at 1%). The cause was [Drop PasswordManager.storyboard](https://app.asana.com/1/137249556945/project/1199230911884351/task/1216591205063596), a step of this project. We would have caught it if we had followed [Testing supported macOS versions](https://app.asana.com/1/137249556945/project/1202500774821704/task/1209979078933553) and run UI tests on older macOS. An earlier storyboard drop (TabBar) also caused a [regression](https://app.asana.com/1/137249556945/project/1199230911884351/task/1218936378996439), which internal testing caught.
|
||
- *Prevention:* when a UI refactor touches views, test it on the oldest supported macOS before merge. This project's VM work makes that cheap.
|
||
- **Demand checked too late.** Who would use VSCode came up only at the end (Sep 29: "how many team members use VS Code?"; Pete suggested a survey). By then the company had dropped Cursor licenses, which weakened the main motivation.
|
||
- *Prevention:* poll the team before scoping a tooling project that depends on adoption.
|
||
- **The goal was framed around one IDE.** The structural work was easier to accept on its own merits than as "steps to VSCode". Reviewers said these improvements "should have been discussed and prioritized for their own benefits".
|
||
- *Prevention:* scope structural cleanups as their own projects and keep tooling goals separate.
|
||
- **The approval aged.** The original design was approved in Oct 2025. By the time the prerequisites landed a year later, the context had changed (Cursor licenses dropped, Xcode 27 builds package resources natively). The follow-up design was then reviewed as a new decision and rejected.
|
||
- *Prevention:* on a long project, re-confirm the plan with the team when the context shifts, before starting the final step.
|
||
|
||
## Discussions
|
||
|
||
**[Convert all macOS modules to Swift Package](https://app.asana.com/1/137249556945/project/1200194497630846/task/1211573210737831) (Oct 2025 – Mar 2026) and its [TD](https://app.asana.com/1/137249556945/project/1202406491309510/task/1211728521308688) — approved 2025-10-24.** The plan: the app code becomes a static library linked by the Xcode app targets, plus a dylib and a launcher app for VSCode debugging only. Brindy asked whether it adds overhead for people who don't use VSCode (no, SPM picks up files automatically) and why iOS wasn't covered. Fernando worried about different linking in Debug and Release (no: Xcode builds keep static linking; the dylib is only used for VSCode). Dominik flagged the missing DBP/NetP support as a blocker; that turned out to apply only to the VSCode setup, so he approved ("this is looking great to me"). The blocker was files shared between targets and the `SPARKLE`/`APPSTORE`/`ALPHA` flags. Removing them became the project's main work: Bitwarden, CrashReporting and AppUpdater moved to local packages, and shared files were moved out of the app and test targets.
|
||
|
||
**Project thread (Sep 29 – Oct 16).** Juan and Jorge asked how many people use VSCode, and whether the risk was worth it. Jorge and Brindy worried about the CoreData migration. Brindy asked for test evidence on every supported macOS ("you need 110% confidence"), and Pete suggested a survey. Outcome: CoreData migration cancelled (not needed with Xcode 27), benefits and build timings added to the description.
|
||
|
||
**[TD: Build the macOS browser code as a Swift package](https://app.asana.com/1/137249556945/project/1202406491309510/task/1219304032604521) (Oct 8–15) — won't do.**
|
||
- Diego: per-target and per-configuration dependencies (Sparkle in the App Store app, Alpha-only libraries), mitigations missing from the PR, an unclear problem statement.
|
||
- Bartek: long-term value for the team; every custom piece adds fragility; `Bundle.module` resources can fail silently.
|
||
- Federico: building against Apple's tooling rarely pays off; who owns it; iOS would drift further.
|
||
- Fernando: pause until the macOS 12 incident postmortem is done.
|
||
- Dominik: lint and `InputFilesChecker` shouldn't be what prevents crashes. Smaller wins exist: tests without a host app (9 of 6,772 failed), buildable folders (pbxproj −8k lines).
|
||
- Andre: split the scope into separate changes.
|
||
- Agreed next steps: buildable folders, unit tests without the host app, modularization in small steps with a TD per step.
|
||
|
||
**[TD: VS Code on the Xcode projects through a build server](https://app.asana.com/1/137249556945/project/1203301625297703/task/1219507745158264) (Oct 15–16) — not adopted.** Federico called it much safer, and Diego's questions were answered: there's no impact on people who don't opt in, and the supply-chain risk needs a tooling triage. Jonathan recommended stopping VSCode support: few people asked for it, and once it's in the repo it becomes a team responsibility. Dominik suggested keeping it local. Result: published as an individual opt-in instruction.
|
||
|
||
## What actions should we take to make future projects faster or better?
|
||
|
||
- Run at least occasional test runs on older macOS runners, including UI tests.
|
||
- Actually test on older macOS versions before release, using VM leases ([[personal/projects/virfield|virfield]]), as [Testing supported macOS versions](https://app.asana.com/1/137249556945/project/1202500774821704/task/1209979078933553) already expects.
|
||
- Check demand before starting tooling projects.
|
||
|
||
## What are the remaining action items?
|
||
|
||
- [ ] Propose occasional test runs on older macOS runners: Alex M, date TBD
|
||
- [ ] VM-based testing on older macOS (virfield): Alex M, date TBD
|
||
- [ ] Remaining refactors and follow-ups, moved to the backlog to continue individually: [1218987523298563](https://app.asana.com/1/137249556945/project/414235014887631/task/1218987523298563), [1219569152209143](https://app.asana.com/1/137249556945/project/1202406491309510/task/1219569152209143), [1209808486380258](https://app.asana.com/1/137249556945/project/1203301625297703/task/1209808486380258), [1219569155002752](https://app.asana.com/1/137249556945/project/1202406491309510/task/1219569155002752)
|
||
- [ ] Pin the final outcome comment on the project task
|
||
|
||
---
|
||
|
||
## Reference: significant events
|
||
|
||
| Date | Event |
|
||
|---|---|
|
||
| 2025-03-27 | Project task created |
|
||
| 2025-04-14 | "Testing supported macOS versions" expectation created |
|
||
| 2025-05-27 | Project started |
|
||
| 2025-10-07 | "Convert all macOS modules to Swift Package" step started |
|
||
| 2025-10-24 | TD: convert all macOS modules to Swift Package approved |
|
||
| 2026-03-06 | Module conversion step done (Bitwarden, CrashReporting, AppUpdater packages; shared files moved) |
|
||
| 2026-07-16 | Storyboard-drop subtasks created |
|
||
| 2026-09-29 | Team questions value and risk on the project task |
|
||
| 2026-10-01 | PasswordManager.storyboard dropped |
|
||
| 2026-10-05 | Storyboards fully dropped; CoreData migration cancelled; VSCode PR #7080 in draft |
|
||
| 2026-10-06 | Status update at Apple Weekly; asked to write a TD |
|
||
| 2026-10-08 | TD: Swift package published |
|
||
| 2026-10-12 | macOS 12 credentials-save crash incident (1.211.0) |
|
||
| 2026-10-15 | Swift package TD closed as won't do; build-server TD published |
|
||
| 2026-10-16 | Build-server TD not adopted; opt-in instruction published; project closed |
|