0 Fork 0

Files

T

Alexey Martemyanov 32cdd16bc4 [2026-10-20] eagle: work/projects/vscode-migration/postmortem.md

2026-10-20 18:24:09 +06:00

8.7 KiB

Raw Blame History

type, project, asana, postmortem_task, started, completed, postmortem_date, dri

type	project	asana	postmortem_task	started	completed	postmortem_date	dri
postmortem	Migration to fully VSCode-supported builds&debugging	https://app.asana.com/1/137249556945/project/1203301625297703/task/1209808486380252	https://app.asana.com/1/137249556945/project/1203301625297703/task/1219573444990290	2025-05-27	2026-10-16	2026-10-20	Alex M

Postmortem: Migration to fully VSCode-supported builds&debugging

For what: Migration to fully VSCode-supported builds&debugging Started: 2025-05-27 (task created 2025-03-27) · Closed: 2026-10-16 · DRI: Alex M Zoom link:

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 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 (2026-10-12; 1h35m user impact, rollout stopped at 1%). The cause was Drop PasswordManager.storyboard, a step of this project. We would have caught it if we had followed Testing supported macOS versions and run UI tests on older macOS. An earlier storyboard drop (TabBar) also caused a regression, 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 (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 (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), as Testing supported macOS versions 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, 1219569152209143, 1209808486380258, 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

8.7 KiB Raw Blame History Unescape Escape