Unreal Engine: Add migration guide

docs/platforms/unreal/configuration/options.mdx

@@ -42,6 +42,12 @@ By default the SDK will try to read this value from the `SENTRY_ENVIRONMENT` env
 
 </ConfigKey>
 
+<ConfigKey name="dist">
+
+Sets the distribution of the application. Distributions are used to disambiguate build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. The dist has a max length of 64 characters.
+
+</ConfigKey>
+
 <ConfigKey name="sample-rate">
 
 Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly.

docs/platforms/unreal/migration/index.mdx

@@ -0,0 +1,162 @@
+---
+title: Migration Guide
+description: "Learn more about migrating to the current version."
+sidebar_order: 8000
+---
+
+<Alert>
+We recommend using this guide starting from the version closes to your current version which might require scrolling further down before jumping to the latest guide.
+</Alert>
+
+## Migrating to 1.0.0
+
+### Breaking changes
+
+#### Sentry Classes Instantiation
+
+Sentry class objects created via `NewObject<T>` in C++ or `ConstructObjectFromClass` in Blueprints now require an explicit call to their `Initialize` method (if available) before use. In Blueprints, it's recommended to use the provided Sentry library functions to create these entities as they automatically call `Initialize` and return a fully initialized, ready-to-use object.
+
+#### Cleanup Public Classes
+
+We cleaned up our public API by removing a few functions and classes to streamline the SDK and remove ambiguities. The following changes were made:
+
+- Removed `USentryId` class and replaced its usages with `FString`
+- Removed `USentrySubsystem::ConfigureScope` function
+- Removed `USentryLibrary::StringToBytesArray` function
+- Removed `USentryLibrary::ByteArrayToString` function
+- Removed `USentryLibrary::SaveStringToFile` function
+- Removed `USentryScope::SetEnvironment` function
+- Removed `USentryScope::GetEnvironment` function
+- Removed `USentryScope::SetDist` function
+- Removed `USentryScope::GetDist` function
+
+#### User feedback
+
+We have reworked the user feedback feature so now it no longer needs to be associated with a specific event and the only required input is the text message. If you were using this functionality in your project consider updating it accordingly:
+
+- Replace `USentryUserFeedback` class references with `USentryFeedback`
+- Replace `USentrySubsystem::CaptureUserFeedback` function usages with `USentrySubsystem::CaptureFeedback`
+- Replace `USentryLibrary::CreateSentryUserFeedback` function usages with `USentryLibrary::CreateSentryFeedback`
+
+```cpp
+USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
+
+FString Message = TEXT("Feedback message");
+FString Name = TEXT("John Doe");
+FString Email = TEXT("[email protected]");
+FString EventId = TEXT("c3829f10764848442d813c4124cf44a0");
+
+// Submitting user feedback before v1.0.0
+
+USentryUserFeedback* Feedback = NewObject<USentryUserFeedback>();
+
+Feedback->Initialize(EventId);
+
+Feedback->SetName(Name);        // optional
+Feedback->SetEmail(Email);      // optional
+Feedback->SetComment(Message);  // optional
+
+SentrySubsystem->CaptureUserFeedback(Feedback);
+
+// Submitting user feedback in v1.0.0
+
+USentryFeedback* Feedback = NewObject<USentryFeedback>();
+
+Feedback->Initialize(Message);
+
+Feedback->SetName(Name);                // optional
+Feedback->SetContactEmail(Email);       // optional
+Feedback->SetAssociatedEvent(EventId);  // optional
+
+SentrySubsystem->CaptureFeedback(Feedback);
+```
+
+#### Tracing
+
+The `USentrySubsystem::StartTransactionWithContextAndOptions` function now takes an `FSentryTransactionOptions` struct instead of a `TMap<FString, FString>`, improving clarity and allowing better extensibility in the future.
+
+Also, the `USentrySamplingContext` class now utilizes `FSentryVariant` instead of strings for custom sampling context values.
+
+```cpp
+USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
+
+// Starting transaction with context and options before v1.0.0
+
+USentryTransactionContext* TransactionContext = ...
+
+TMap<FString, FString> Options;
+Options.Add("key1", "value1");
+Options.Add("key2", "value2");
+
+SentrySubsystem->StartTransactionWithContextAndOptions(TransactionContext, Options);
+
+// Starting transaction with context and options in v1.0.0
+
+USentryTransactionContext* TransactionContext = ...
+
+FSentryTransactionOptions Options;
+Options.CustomSamplingContext.Add("key1", FSentryVariant("value1"));
+Options.CustomSamplingContext.Add("key2", FSentryVariant("value2"));
+
+SentrySubsystem->StartTransactionWithContextAndOptions(TransactionContext, Options);
+```
+
+#### Event ID format (Windows/Linux)
+
+On Windows and Linux, `ToString` function of `SentryId` class now returns the sanitized string that doesn't contain dashes.
+
+#### Global scope configuration
+
+With the removal of `USentrySubsystem::ConfigureScope` global scope values (tags, context, attachments, etc.) should now be configured directly via the subsystem interface.
+
+```cpp
+USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
+
+// Configuring global scope before v1.0.0
+
+SentrySubsystem->ConfigureScope(FConfigureScopeNativeDelegate::CreateLambda([](USentryScope* Scope)
+{
+    Scope->SetTag(...);
+    Scope->SetContext(...);
+    Scope->AddAttachment(...);
+}));
+
+// Configuring global scope in v1.0.0
+
+SentrySubsystem->SetTag(...);
+SentrySubsystem->SetContext(...);
+SentrySubsystem->AddAttachment(...);
+```
+
+### Issue Grouping
+
+The Unreal SDK no longer modifies call stacks for assertion events by trimming the topmost frames related to the engine's internal assertion handling logic. This was previously done to work around the case where all assertions were grouped into a single Sentry issue. With this change, issue grouping is now fully handled by the Sentry server.
+
+### SDK Configuration Changes
+
+- The <PlatformIdentifier name="environment" /> and <PlatformIdentifier name="dist" /> properties must now be set in the plugin settings and can no longer be modified programmatically via scope configuration.
+
+- Sentry can no longer be disabled for specific platforms using the `Enable for Build Platform Types` option in the plugin settings (`General -> Misc`) or the EnableTargetPlatforms property in the project configuration file.
+
+- If upgrading from a version prior to 0.9.0 legacy settings `DsnUrl`, `EnableVerboseLogging` and `EnableStackTrace` will no longer be read from the project configuration file automatically. Instead, you must re-set them in plugin settings to adopt the new format.
+
+- On mobile platforms, the default traces sampler will no longer be created automatically. You must now explicitly set the `Traces Sampler` property in the plugin settings to enable performance monitoring (`General -> Performance Monitoring`).
+
+### Crash Reporter Changes
+
+The `Epic Account Id` and `Login Id` are no longer included in the `Crash Info` context for crashes captured on Windows and Linux using the default Crash Reporter. These fields are intended for internal use by Epic Games and provide no meaningful value externally.
+
+## Migrating to 0.19.0
+
+### Breaking changes
+
+- Renamed `OnError` delagate property of `FSentryOutputDeviceError` class to `OnAssert`
+
+## Migrating to 0.15.0
+
+### Breaking changes
+
+To enable capturing editor crashes `USentrySubsystem` base class has been changed to `UEngineSubsystem`.
+
+- If you're using the plugin's Blueprint API, you will need to recreate all `Get Sentry Subsystem` nodes.
+- If you're using the plugin's C++ API, update your implementation to access `USentrySubsystem` via the `GEngine` pointer.