docs: Add KSCrash migration strategy document

[NinjaLikesCheez]

📜 Description

Adds a develop-doc with the two potential migration strategies for KSCrash along with a recommendation of which approach to take.

💡 Motivation and Context

Early alignment on the strategy will allow us to start landing code changes incrementally sooner rather than later

📝 Checklist

You have to check all boxes before merging:

• I added tests to verify the changes.
• No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
• I updated the docs if needed.
• I updated the wizard if needed.
• Review from the native team if needed.
• No breaking change or entry added to the changelog.
• No breaking change for hybrid SDKs or communicated to hybrid SDKs.
• If I added a new public API, I also added it to the SentryObjC wrapper.

#skip-changelog

Closes #8095

[philprime]

My main concern with this approach is that we have to add KSCrash to the dependencies in Package.swift, and every user needs to check it out, even if they do not use it. There is no conditional compilation flag for Package.swift

[NinjaLikesCheez]

Yup, that is the main downside (one I will note in the doc as well). In testing it's a ~3.3MB checkout with SPM which seemed negligible - if you know of a better way to integrate this (until the cut over) I'm happy to not add it as a direct dependency.

[NinjaLikesCheez]

@itaybre brought up a good point of using env vars to dictate whether a package is installed or not - see #8094 (comment)

[philprime]

How can the env var be set in UI?

[NinjaLikesCheez]

Good point - will look into that - it's likely not an issue until we migrate sample apps to package references as Xcode will need a new target to link KSCrash with Xcode SPM integration

[NinjaLikesCheez]

The only reliable way I can see is to open Xcode with an env var set ENABLE_KSCRASH=1 open Sentry.xcworkspace.

[itaybre]

Can we conditionally add the KSCrash dependency like we did with EXPERIMENTAL_SPM? see this PR
This way we won't force users to download KSCrash (yet)

[NinjaLikesCheez]

Oh nice, didn't think of this - addressed in 70f48e7 thanks!

[philprime]

In that case I stand corrected, but @itaybre how can EXPERIMENTAL_SPM_BUILDS be configured from Xcode UI?

[itaybre]

Good question, I think we only tested this using pure SPM.

We would need to open xcode using EXPERIMENTAL_SPM_BUILDS=1 open Project.xcproj probably to set up this env variable

[philipphofmann]

Thanks for putting this together @NinjaLikesCheez.

Very important points that we need to address somewhere. Maybe they should be part of this document. If they're out of scope, please let me know:

1. Version update strategy — do we always point to the latest kscrash, or pin to a version and bump deliberately?
2. Should we have our own kscrash fork, or do we directly integrate kscrash? The benefit of our own fork would be that we won't be blocked by incidents and hotfixes. The key would be, obviously, that this fork, by default, should always be the same as KSCrash.

[philipphofmann]

My maybe a bit crazy and bold proposal

Option C: Remove SentryCrash in v10 completely

Don't keep SentryCrash around at all. v10 ships KSCrash only. Every user downloads KSCrash as a dependency, because they need it.

Pros

• Solves the dual-existence problem — no two integrations to keep in sync
• No environment variable needed
• Drastically reduces complexity and maintenance: we don't maintain SentryCrash side by side
• One code path to test and ship
• Don't worry about edge cases when users switch between KSCrash and SentryCrash.

Cons

• Users can't switch back to SentryCrash. If they're not happy with kscrash, they stay on v9.

If people really, really want it, we add an extra target that only includes SentryCrash in v10.

[supervacuus]

I think that is the plan. At least I would have severely misunderstood what we are going for, if that wasn't the plan.

The two options are meant as: how do we handle migration work until v10 is released, as a separate branch that requires continuous synchronization in both directions, or have KSCrash be part of v10 from the get-go (as much as that is possible, afaics @NinjaLikesCheez still struggles with adapting the build setup).

But there is no SentryCrash in v10 (unless we fail to get a stable solution with KSCrash by then). But during migration, we must keep all variants alive if we colocate the KSCrash migration on main. Simply because KSCrash might not work well enough for other v10 developments from day 1. But the idea is not to keep this up until the release; ideally, the KSCrash integration is stable well before release, so we can drop SentryCrash from the v10 build configs.

At least my understanding of the current situation.

[NinjaLikesCheez]

Sorry that this wasn't clear, that is indeed the plan.

This document is intending to describe the migration path from the development perspective where we need both around for a bit (so that v9 builds get SentryCrash, v10 builds get SentryCrash, and v10 + KSCrash builds get KSCrash until it's stable enough to drop SentryCrash altogether).

I will update the document to better reflect that we're aiming for this to be the default crash handler in v10.

[philipphofmann]

Now it's clearer thanks 95d5afa

I would also mention this document / the migration phase clearly in the linear project, if we're not doing this already, please: https://linear.app/getsentry/project/kscrash-migration-9c21f604afac/overview

[philipphofmann]

I'm not sure if that would work for pre-built binaries. Did we already decide to ditch these in v10?

[NinjaLikesCheez]

Indeed - that will happen with #8133. It's not intended to be compiled or shipped to consumers until v10

[philipphofmann]

I think it would be great if you could add to the document that we are not worrying about pre-built binaries during the migration phase to speed things up, so it's crystal clear.

[supervacuus]

The migration work will certainly teach us humility, but

• Should we have our own kscrash fork, or do we directly integrate kscrash? The benefit of our own fork would be that we won't be blocked by incidents and hotfixes. The key would be, obviously, that this fork, by default, should always be the same as KSCrash.

We will start from a fork and try to upstream changes as much as possible, or create adapters on the sentry-cocoa side (even those might require upstream changes). Ideally, we can switch to the vanilla upstream at some point. But that is not a goal for the v10 release. It could also be the case that the fork will exist ad infinitum.

• Version update strategy — do we always point to the latest kscrash, or pin to a version and bump deliberately?

This depends on the above. I expect the fork to exist for a while, meaning we bump regularly, but whenever it makes sense. Even when a fork is no longer necessary, I think it is reasonable to pin, given how core behavioral changes are to the SDK (and also regarding the rather liberal versioning upstream).

[philipphofmann]

We will start from a fork and try to upstream changes as much as possible, or create adapters on the sentry-cocoa side (even those might require upstream changes). Ideally, we can switch to the vanilla upstream at some point. But that is not a goal for the v10 release. It could also be the case that the fork will exist ad infinitum.

I would really try to do vanilla as much as possible. If not, I see the risk that the fork deviates, and we put logic into the fork that should actually be in the Cocoa SDK. During the migration phase, which will be experimental, we don't need to worry about KSCrash's stability issues.