[2026-10-20] eagle: work/projects/vscode-migration/postmortem.md
This commit is contained in:
Alexey Martemyanov committed
1 parent
5a9de9834e
commit
32cdd16bc4
1 file changed
+98
@@ -0,0 +1,98 @@
|
||||
---
|
||||
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:** <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 first TD got specific objections, and a narrower, opt-in TD followed within two days.
|
||||
- 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 big TD came after most of the work.** The SPM package design was written after the 2026-10-06 Apple Weekly status update, when most prerequisites had already landed.
|
||||
- *Prevention:* write the TD for the end state before starting the steps.
|
||||
|
||||
## Discussions
|
||||
|
||||
**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 |
|
||||
| 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 |
|
||||
Reference in new issue
Block a user