From 277a748b6157cbd9ae8d9ab33cf34d08c3a25a3c Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 27 Nov 2025 11:59:26 +0100 Subject: [PATCH 01/14] feat: Breaking changes in SDK --- .../sdk/processes/breaking_changes.mdx | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 develop-docs/sdk/processes/breaking_changes.mdx diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx new file mode 100644 index 0000000000000..d7822b9e4b64e --- /dev/null +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -0,0 +1,93 @@ +--- +title: Breaking Changes +description: Learn about our principles and processes when it comes to introducing breaking changes. +sidebar_order: 4 +--- + +Code ages, features and APIs become obsolete. All of this is expected when working on a library for an extended period of time. Deciding what to drop, how, and when, is not straightforward. The developers' wishes to evolve a codebase inevitably clash with the user experience of the folks using the codebase. + +At Sentry, user experience is a core part of our [SDK development values](/sdk/philosophy). Evolving our SDKs is ultimately a balancing act between what we as engineers think is right (for us, for the health of the codebase, and for the users), and the ease of use on the user side. + +This page aims to provide a basic set of guidelines how to think about this topic, to help drive discussions, and ultimately empower SDK engineers to make good decisions. We'll cover: +- [What changes to be mindful of.](#changes-to-be-mindful-of) There are changes that are technically not breaking, but should go out in a major release. And on the other hand, there are changes that are technically breaking, but can be released in a minor version. +- [Things to consider when introducing a breaking change.](#how-to-introduce-breaking-changes) +- [Recipes & examples](#recipes) + +Dealing with breaking changes (or even deciding what is one) is by no means an easy problem with a clear-cut solution, so discussing on a case-by-case basis with your teammates is always a good idea and very much encouraged. + + +## Changes to Be Mindful Of + +Is something a change that should go out in a major release? Answering this question is often the hardest part of the process. Going strictly by semantic versioning rules, where we simply evaluate whether the API has undergone a backwards-incompatible change, doesn't cover all cases where we might significantly alter a user's experience using Sentry. + +In general, changes that the user needs to adapt to or changes that significantly alter the behavior of the SDK require scrutiny. + + +### SDK API Surface Changes + +The most obvious kind of breaking changes is changing the way the user interacts with the public API of the SDK, for instance: +- Dropping or renaming part of the API +- Dropping or renaming an argument to an API function +- Changing the type of an argument to an API function and not accepting the previous type anymore + +In some SDKs, the line between public and private API is unclear. If unsure, discuss with your teammates. Some pointers: +- Is the API mentioned in the user-facing docs? Then it's probably public and you should consider making changes to it in a major release. +- Was the code you're changing solely created for an internal purpose? Is it a utility function, or a helper function we added to make testing easier? Then it's fine to change. +- Can you reasonably assume a significant portion of the user base is using this? + +Naturally, the language of your SDK and the community around it also affects what is generally considered a breaking change. Some languages provide their own guidelines: +- [.NET](https://learn.microsoft.com/en-gb/dotnet/core/compatibility/library-change-rules) + + +### Changes in the Product + +We also need to be mindful of what the SDK change might cause in the product. Sometimes we're forcing users to make changes in their use of Sentry because we, for example, broke a dashboard by renaming a span attribute. However, we also don't want to be in a position where we can't fix an attribute name without releasing a new major version of the SDK. That's also not great UX. + +In general, we consider changes to the following product-side features breaking: +- **Grouping:** An SDK change might result in error events being grouped differently, because we remove, add or change some of the data on the event that is used in the grouping algorithm on the server. The logic that governs grouping [lives in the monolith](https://github.com/getsentry/sentry/tree/742439ff2894dd187ada47cf96ee3f2f9d31e828/src/sentry/grouping). When you think a change might affect grouping, it's recommended to try the SDK with the change yourself and check in Sentry whether grouping is preserved. +- **Dashboards:** A user dashboards set up that filter on specific data and we change that data. For instance, changing a span's `op` might mean a dashboard showing those spans will be empty after an SDK update. +- **Alerts:** Alerts might stop firing because we've changed an attribute. + +Changes to grouping are always considered breaking and should be released in a major version. Changes to dashboards and alerts need closer inspection. + + +#### Gauging the Impact in the Product + +In order to gauge the impact of the change, you can consult internal stats on how many alerts or dashboards are using the specific property: +- You can reach out to the Data team. +- If you have Redash access (which you can request via the IT helpdesk), you can execute the queries yourself. (TODO link/manual) + +If you find out only a small number of users is using the attribute you're about to change, you can consider releasing it in a minor version and reaching out to the folks affected directly. The Support team will be able to help. + +The caveat to gauging impact this way is that self-hosted Sentries are not included. However, it still provides a good baseline: attribute usage stats on SaaS are unlikely to be vastly different from those on self-hosted. + + +### SDK Behavior Changes + +There are also changes that technically don't require the user to adapt, but they might impact their UX significantly. These tend to be subtle and often need to be evaluated on a case-by-case basis. Be especially mindful of: + +- Changes that affect the user's quota. The SDK might, for instance, start sending much more spans because we auto-enabled an integration or changed an option from opt-in to on by default. + + +## Introducing Breaking Changes + +So you're considering introducing a potentially breaking change. + +Some of this is, again, dependent on your SDK's language. Some language communities are generally more open to new majors, while in others you can expect that introducing a new major release will create significant friction for folks to upgrade. + +In any case, introducing a new major release creates friction. The harder it is to upgrade, the less people will actually do it. We want to avoid folks staying on old releases because upgrading is too much of a hassle for them as much as we can. + +What increases friction: +- Piling up breaking changes. Especially if you don't have major releases often, you might be tempted to queue a lot of breaking changes. + +What lessens friction: +- A great migration guide. Make sure to include copy-pastable before-after examples. +- Deprecation warnings. +- Trying to do the upgrade yourself (with the help of an LLM?). +- An automated way of doing the upgrade (codemods?). +- Call outs in docs and changelogs. + + +## Recipes + +TODO From dacc51089d7db8b444067e136a9f5941a5ae648a Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 13:48:29 +0100 Subject: [PATCH 02/14] . --- .../sdk/processes/breaking_changes.mdx | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index d7822b9e4b64e..5c0d6d09cf621 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -4,7 +4,7 @@ description: Learn about our principles and processes when it comes to introduci sidebar_order: 4 --- -Code ages, features and APIs become obsolete. All of this is expected when working on a library for an extended period of time. Deciding what to drop, how, and when, is not straightforward. The developers' wishes to evolve a codebase inevitably clash with the user experience of the folks using the codebase. +Code ages, features and APIs become obsolete. All of this is expected when working on a library for an extended period of time. Deciding what to drop, how, and when, is not straightforward. Our wishes as developers to evolve a codebase inevitably clash with the user experience of the folks using it. At Sentry, user experience is a core part of our [SDK development values](/sdk/philosophy). Evolving our SDKs is ultimately a balancing act between what we as engineers think is right (for us, for the health of the codebase, and for the users), and the ease of use on the user side. @@ -44,8 +44,8 @@ Naturally, the language of your SDK and the community around it also affects wha We also need to be mindful of what the SDK change might cause in the product. Sometimes we're forcing users to make changes in their use of Sentry because we, for example, broke a dashboard by renaming a span attribute. However, we also don't want to be in a position where we can't fix an attribute name without releasing a new major version of the SDK. That's also not great UX. In general, we consider changes to the following product-side features breaking: -- **Grouping:** An SDK change might result in error events being grouped differently, because we remove, add or change some of the data on the event that is used in the grouping algorithm on the server. The logic that governs grouping [lives in the monolith](https://github.com/getsentry/sentry/tree/742439ff2894dd187ada47cf96ee3f2f9d31e828/src/sentry/grouping). When you think a change might affect grouping, it's recommended to try the SDK with the change yourself and check in Sentry whether grouping is preserved. -- **Dashboards:** A user dashboards set up that filter on specific data and we change that data. For instance, changing a span's `op` might mean a dashboard showing those spans will be empty after an SDK update. +- **Grouping:** An SDK change might result in error events being grouped differently, because we remove, add or change some of the data on the event that is used in the grouping algorithm on the server. When you think a change might affect grouping, it's recommended to try the change yourself and check in Sentry to see if grouping is preserved. +- **Dashboards:** A user has set up a dashboard that filters on specific data and we change that data. For instance, changing a span's `op` might mean a dashboard showing those spans will be empty after an SDK update. - **Alerts:** Alerts might stop firing because we've changed an attribute. Changes to grouping are always considered breaking and should be released in a major version. Changes to dashboards and alerts need closer inspection. @@ -55,7 +55,11 @@ Changes to grouping are always considered breaking and should be released in a m In order to gauge the impact of the change, you can consult internal stats on how many alerts or dashboards are using the specific property: - You can reach out to the Data team. -- If you have Redash access (which you can request via the IT helpdesk), you can execute the queries yourself. (TODO link/manual) +- If you have Redash access (which you can request via the IT helpdesk), you can execute the queries yourself. The easiest way to do this is: + - Find an example dashboard that looks similar to what you need (for instance, https://redash.getsentry.net/dashboards/372-span-status-usage-in-widgets-and-alerts can be modified for checking span-related alerts) + - Navigate to a specific widget on the dashboard, open a dropdown and click on `View Query` + - Fork the query on the top right + - Modify as you need and execute If you find out only a small number of users is using the attribute you're about to change, you can consider releasing it in a minor version and reaching out to the folks affected directly. The Support team will be able to help. @@ -67,6 +71,7 @@ The caveat to gauging impact this way is that self-hosted Sentries are not inclu There are also changes that technically don't require the user to adapt, but they might impact their UX significantly. These tend to be subtle and often need to be evaluated on a case-by-case basis. Be especially mindful of: - Changes that affect the user's quota. The SDK might, for instance, start sending much more spans because we auto-enabled an integration or changed an option from opt-in to on by default. +- Changes that might result in events being dropped. We might, for instance, increase or remove a default trimming limit in the SDK, which might result in payloads big enough that they are rejected during ingestion. ## Introducing Breaking Changes @@ -75,19 +80,14 @@ So you're considering introducing a potentially breaking change. Some of this is, again, dependent on your SDK's language. Some language communities are generally more open to new majors, while in others you can expect that introducing a new major release will create significant friction for folks to upgrade. -In any case, introducing a new major release creates friction. The harder it is to upgrade, the less people will actually do it. We want to avoid folks staying on old releases because upgrading is too much of a hassle for them as much as we can. +In any case, introducing a new major release creates friction. The harder it is to upgrade, the less people will actually do it. We want to avoid folks staying on old releases because upgrading is too much of a hassle for them. -What increases friction: -- Piling up breaking changes. Especially if you don't have major releases often, you might be tempted to queue a lot of breaking changes. +**Factors increasing friction:** +- Piling up breaking changes. Especially if you don't have major releases often, you might be tempted to queue a lot of breaking changes into one release. -What lessens friction: -- A great migration guide. Make sure to include copy-pastable before-after examples. -- Deprecation warnings. -- Trying to do the upgrade yourself (with the help of an LLM?). -- An automated way of doing the upgrade (codemods?). -- Call outs in docs and changelogs. - - -## Recipes - -TODO +**How to lessen friction:** +- Call-outs in relevant places in the docs and in the changelog. +- Deprecation warnings that a breaking change is coming. +- A polished migration guide with a lot of easily copy-pastable examples. +- Trying to do the upgrade yourself on a test app. Instruct an LLM to do the update using your migration guide and see how well it works. +- Providing a tool that helps with the upgrade, for example using codemods. From c259934fadf222f4dd070d664810facd85c35628 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 13:50:09 +0100 Subject: [PATCH 03/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index 5c0d6d09cf621..36fad5476f9e0 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -8,10 +8,7 @@ Code ages, features and APIs become obsolete. All of this is expected when worki At Sentry, user experience is a core part of our [SDK development values](/sdk/philosophy). Evolving our SDKs is ultimately a balancing act between what we as engineers think is right (for us, for the health of the codebase, and for the users), and the ease of use on the user side. -This page aims to provide a basic set of guidelines how to think about this topic, to help drive discussions, and ultimately empower SDK engineers to make good decisions. We'll cover: -- [What changes to be mindful of.](#changes-to-be-mindful-of) There are changes that are technically not breaking, but should go out in a major release. And on the other hand, there are changes that are technically breaking, but can be released in a minor version. -- [Things to consider when introducing a breaking change.](#how-to-introduce-breaking-changes) -- [Recipes & examples](#recipes) +This page aims to provide a basic set of guidelines how to think about this topic, to help drive discussions, and ultimately empower SDK engineers to make good decisions. Dealing with breaking changes (or even deciding what is one) is by no means an easy problem with a clear-cut solution, so discussing on a case-by-case basis with your teammates is always a good idea and very much encouraged. From 4c42a0a0e2aa91b439d11b89f046317ee404eb90 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 14:01:08 +0100 Subject: [PATCH 04/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index 36fad5476f9e0..a4c66b839dcba 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -79,12 +79,15 @@ Some of this is, again, dependent on your SDK's language. Some language communit In any case, introducing a new major release creates friction. The harder it is to upgrade, the less people will actually do it. We want to avoid folks staying on old releases because upgrading is too much of a hassle for them. -**Factors increasing friction:** +### Factors Increasing Friction + - Piling up breaking changes. Especially if you don't have major releases often, you might be tempted to queue a lot of breaking changes into one release. -**How to lessen friction:** +### How to Lessen Friction + - Call-outs in relevant places in the docs and in the changelog. - Deprecation warnings that a breaking change is coming. +- Supporting an intermediate period where both the old and the new way of doing things works. - A polished migration guide with a lot of easily copy-pastable examples. - Trying to do the upgrade yourself on a test app. Instruct an LLM to do the update using your migration guide and see how well it works. - Providing a tool that helps with the upgrade, for example using codemods. From 94af87b8a421a6dda103a1c9180ed8fc1e9cb152 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 14:03:49 +0100 Subject: [PATCH 05/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index a4c66b839dcba..295183acf7b50 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -45,7 +45,7 @@ In general, we consider changes to the following product-side features breaking: - **Dashboards:** A user has set up a dashboard that filters on specific data and we change that data. For instance, changing a span's `op` might mean a dashboard showing those spans will be empty after an SDK update. - **Alerts:** Alerts might stop firing because we've changed an attribute. -Changes to grouping are always considered breaking and should be released in a major version. Changes to dashboards and alerts need closer inspection. +Changes to grouping are always considered breaking and should be released in a major version. Changes to dashboards and alerts need closer inspection. For making a data-driven decision, you can try to gauge the impact in the product using our data analytics tools. #### Gauging the Impact in the Product From bd129f797cc8c5cbf04b4d54fe65adfb03b4cfa4 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 14:04:06 +0100 Subject: [PATCH 06/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index 295183acf7b50..640d4bde88375 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -45,7 +45,7 @@ In general, we consider changes to the following product-side features breaking: - **Dashboards:** A user has set up a dashboard that filters on specific data and we change that data. For instance, changing a span's `op` might mean a dashboard showing those spans will be empty after an SDK update. - **Alerts:** Alerts might stop firing because we've changed an attribute. -Changes to grouping are always considered breaking and should be released in a major version. Changes to dashboards and alerts need closer inspection. For making a data-driven decision, you can try to gauge the impact in the product using our data analytics tools. +Changes to grouping are always considered breaking and should be released in a major version. Changes to dashboards and alerts need closer inspection. You can try to gauge the impact in the product using our data analytics tools. #### Gauging the Impact in the Product From c0de72b06940d5d8889c86138026b6373a7cd78f Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 14:04:40 +0100 Subject: [PATCH 07/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index 640d4bde88375..05229ca245f8f 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -53,7 +53,7 @@ Changes to grouping are always considered breaking and should be released in a m In order to gauge the impact of the change, you can consult internal stats on how many alerts or dashboards are using the specific property: - You can reach out to the Data team. - If you have Redash access (which you can request via the IT helpdesk), you can execute the queries yourself. The easiest way to do this is: - - Find an example dashboard that looks similar to what you need (for instance, https://redash.getsentry.net/dashboards/372-span-status-usage-in-widgets-and-alerts can be modified for checking span-related alerts) + - Find an example dashboard that looks similar to what you need (for instance, [this dashboard](https://redash.getsentry.net/dashboards/372-span-status-usage-in-widgets-and-alerts) can be adapted for checking span-related alerts) - Navigate to a specific widget on the dashboard, open a dropdown and click on `View Query` - Fork the query on the top right - Modify as you need and execute From befd9f2a0a575db343d312307546470040be6880 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 14:18:13 +0100 Subject: [PATCH 08/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index 05229ca245f8f..6b67edfbc598a 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -38,9 +38,9 @@ Naturally, the language of your SDK and the community around it also affects wha ### Changes in the Product -We also need to be mindful of what the SDK change might cause in the product. Sometimes we're forcing users to make changes in their use of Sentry because we, for example, broke a dashboard by renaming a span attribute. However, we also don't want to be in a position where we can't fix an attribute name without releasing a new major version of the SDK. That's also not great UX. +We also need to be mindful of what the SDK change might cause in the product. Sometimes we're forcing users to make changes in their use of Sentry because we, for example, broke a dashboard by renaming a span attribute. However, we also don't want to be in a position where we can't fix an attribute name without releasing a new major version of the SDK. Having to adopt a new major version every month is also not great UX. -In general, we consider changes to the following product-side features breaking: +In general, we consider changes to the following product-side problematic: - **Grouping:** An SDK change might result in error events being grouped differently, because we remove, add or change some of the data on the event that is used in the grouping algorithm on the server. When you think a change might affect grouping, it's recommended to try the change yourself and check in Sentry to see if grouping is preserved. - **Dashboards:** A user has set up a dashboard that filters on specific data and we change that data. For instance, changing a span's `op` might mean a dashboard showing those spans will be empty after an SDK update. - **Alerts:** Alerts might stop firing because we've changed an attribute. From 6470fd49262427bd4ebe7f7c1c97c442d5c1221d Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 14:31:20 +0100 Subject: [PATCH 09/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index 6b67edfbc598a..c3d6865cd63ee 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -45,7 +45,7 @@ In general, we consider changes to the following product-side problematic: - **Dashboards:** A user has set up a dashboard that filters on specific data and we change that data. For instance, changing a span's `op` might mean a dashboard showing those spans will be empty after an SDK update. - **Alerts:** Alerts might stop firing because we've changed an attribute. -Changes to grouping are always considered breaking and should be released in a major version. Changes to dashboards and alerts need closer inspection. You can try to gauge the impact in the product using our data analytics tools. +Changes to grouping are always considered breaking and should be released in a major version. Changes to dashboards and alerts need closer inspection. In order to make a good decision, you can try to estimate how many users are affected using our data analytics tools. #### Gauging the Impact in the Product @@ -73,21 +73,23 @@ There are also changes that technically don't require the user to adapt, but the ## Introducing Breaking Changes -So you're considering introducing a potentially breaking change. +So you're considering introducing a breaking change. How can you do this in a way that's least painful for the users? -Some of this is, again, dependent on your SDK's language. Some language communities are generally more open to new majors, while in others you can expect that introducing a new major release will create significant friction for folks to upgrade. +Some of this is, again, dependent on your SDK's language. Some language communities are generally more open to new majors, while in others you can expect that introducing a new major release will mean folks will be less likely to upgrade. -In any case, introducing a new major release creates friction. The harder it is to upgrade, the less people will actually do it. We want to avoid folks staying on old releases because upgrading is too much of a hassle for them. +In any case, introducing a new major release creates friction. The harder it is to upgrade, the less people will actually do it. We want to minimize the number of folks staying on old releases because upgrading is too much of a hassle for them. + +Fortunately, there is always a lot you can do (and not do) to make the upgrade process smoother. ### Factors Increasing Friction - Piling up breaking changes. Especially if you don't have major releases often, you might be tempted to queue a lot of breaking changes into one release. -### How to Lessen Friction +### Ways to Lessen Friction - Call-outs in relevant places in the docs and in the changelog. - Deprecation warnings that a breaking change is coming. - Supporting an intermediate period where both the old and the new way of doing things works. -- A polished migration guide with a lot of easily copy-pastable examples. +- A polished migration guide with a lot of easily copy-pastable before-and-after examples. - Trying to do the upgrade yourself on a test app. Instruct an LLM to do the update using your migration guide and see how well it works. - Providing a tool that helps with the upgrade, for example using codemods. From d6f1ccfcb27f8e8c24e0c18e122782a086ed84b0 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 14:40:46 +0100 Subject: [PATCH 10/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index c3d6865cd63ee..8e2755ea87591 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -15,7 +15,7 @@ Dealing with breaking changes (or even deciding what is one) is by no means an e ## Changes to Be Mindful Of -Is something a change that should go out in a major release? Answering this question is often the hardest part of the process. Going strictly by semantic versioning rules, where we simply evaluate whether the API has undergone a backwards-incompatible change, doesn't cover all cases where we might significantly alter a user's experience using Sentry. +Is something a change that should go out in a major release? Answering this question is often the hardest part of the process. Going strictly by semantic versioning rules, where we simply evaluate whether the API has undergone a backwards-incompatible change, doesn't cover all cases where we might be significantly altering a user's experience using Sentry. In general, changes that the user needs to adapt to or changes that significantly alter the behavior of the SDK require scrutiny. From 5681fae5fdc1e7d7b2b293e1c2b47d37fff1ccad Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 14:48:14 +0100 Subject: [PATCH 11/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index 8e2755ea87591..9b4812798e383 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -40,7 +40,7 @@ Naturally, the language of your SDK and the community around it also affects wha We also need to be mindful of what the SDK change might cause in the product. Sometimes we're forcing users to make changes in their use of Sentry because we, for example, broke a dashboard by renaming a span attribute. However, we also don't want to be in a position where we can't fix an attribute name without releasing a new major version of the SDK. Having to adopt a new major version every month is also not great UX. -In general, we consider changes to the following product-side problematic: +In general, we consider changes to the following product-side features problematic: - **Grouping:** An SDK change might result in error events being grouped differently, because we remove, add or change some of the data on the event that is used in the grouping algorithm on the server. When you think a change might affect grouping, it's recommended to try the change yourself and check in Sentry to see if grouping is preserved. - **Dashboards:** A user has set up a dashboard that filters on specific data and we change that data. For instance, changing a span's `op` might mean a dashboard showing those spans will be empty after an SDK update. - **Alerts:** Alerts might stop firing because we've changed an attribute. From d1ed29ba3c7855feee0c95baa23eb78775a0ed7e Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 14:50:13 +0100 Subject: [PATCH 12/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index 9b4812798e383..f4fb68fa9222a 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -54,7 +54,7 @@ In order to gauge the impact of the change, you can consult internal stats on ho - You can reach out to the Data team. - If you have Redash access (which you can request via the IT helpdesk), you can execute the queries yourself. The easiest way to do this is: - Find an example dashboard that looks similar to what you need (for instance, [this dashboard](https://redash.getsentry.net/dashboards/372-span-status-usage-in-widgets-and-alerts) can be adapted for checking span-related alerts) - - Navigate to a specific widget on the dashboard, open a dropdown and click on `View Query` + - Navigate to a specific widget on the dashboard, open the dropdown menu and click on `View Query` - Fork the query on the top right - Modify as you need and execute From b1f7e8d4093759c7e8d340897e7c3326e23381da Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 14:58:26 +0100 Subject: [PATCH 13/14] . --- develop-docs/sdk/processes/breaking_changes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index f4fb68fa9222a..2b93d4feaa2eb 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -40,7 +40,7 @@ Naturally, the language of your SDK and the community around it also affects wha We also need to be mindful of what the SDK change might cause in the product. Sometimes we're forcing users to make changes in their use of Sentry because we, for example, broke a dashboard by renaming a span attribute. However, we also don't want to be in a position where we can't fix an attribute name without releasing a new major version of the SDK. Having to adopt a new major version every month is also not great UX. -In general, we consider changes to the following product-side features problematic: +In general, we consider changes to the following product-side features potentially problematic: - **Grouping:** An SDK change might result in error events being grouped differently, because we remove, add or change some of the data on the event that is used in the grouping algorithm on the server. When you think a change might affect grouping, it's recommended to try the change yourself and check in Sentry to see if grouping is preserved. - **Dashboards:** A user has set up a dashboard that filters on specific data and we change that data. For instance, changing a span's `op` might mean a dashboard showing those spans will be empty after an SDK update. - **Alerts:** Alerts might stop firing because we've changed an attribute. From 6bf3c212f621abc21469fdafbfeed5be73d3456f Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 28 Nov 2025 17:12:12 +0100 Subject: [PATCH 14/14] Apply suggestions from code review Co-authored-by: Daniel Griesser --- develop-docs/sdk/processes/breaking_changes.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/processes/breaking_changes.mdx b/develop-docs/sdk/processes/breaking_changes.mdx index 2b93d4feaa2eb..24f6fc659d2d9 100644 --- a/develop-docs/sdk/processes/breaking_changes.mdx +++ b/develop-docs/sdk/processes/breaking_changes.mdx @@ -45,7 +45,7 @@ In general, we consider changes to the following product-side features potential - **Dashboards:** A user has set up a dashboard that filters on specific data and we change that data. For instance, changing a span's `op` might mean a dashboard showing those spans will be empty after an SDK update. - **Alerts:** Alerts might stop firing because we've changed an attribute. -Changes to grouping are always considered breaking and should be released in a major version. Changes to dashboards and alerts need closer inspection. In order to make a good decision, you can try to estimate how many users are affected using our data analytics tools. +Changes to grouping, dashboards and alerts need closer inspection. In order to make a good decision, you can try to estimate how many users are affected using our data analytics tools. It always needs a human/team to weigh in. #### Gauging the Impact in the Product @@ -93,3 +93,4 @@ Fortunately, there is always a lot you can do (and not do) to make the upgrade p - A polished migration guide with a lot of easily copy-pastable before-and-after examples. - Trying to do the upgrade yourself on a test app. Instruct an LLM to do the update using your migration guide and see how well it works. - Providing a tool that helps with the upgrade, for example using codemods. +- Maintain deprecated APIs, if possible, for another major version.