diff --git a/packages/web/docs/public/changelog/2025-01-10-static-breaking-change-threshold/ui.png b/packages/web/docs/public/changelog/2025-01-10-static-breaking-change-threshold/ui.png new file mode 100644 index 000000000..56520bbad Binary files /dev/null and b/packages/web/docs/public/changelog/2025-01-10-static-breaking-change-threshold/ui.png differ diff --git a/packages/web/docs/public/docs/pages/management/target-conditional-breaking-changes.png b/packages/web/docs/public/docs/pages/management/target-conditional-breaking-changes.png index af2522551..56520bbad 100644 Binary files a/packages/web/docs/public/docs/pages/management/target-conditional-breaking-changes.png and b/packages/web/docs/public/docs/pages/management/target-conditional-breaking-changes.png differ diff --git a/packages/web/docs/src/authors.ts b/packages/web/docs/src/authors.ts index bee74ee28..d4776c555 100644 --- a/packages/web/docs/src/authors.ts +++ b/packages/web/docs/src/authors.ts @@ -46,4 +46,9 @@ export const authors: Record = { link: 'https://github.com/dotansimha', github: 'dotansimha', }, + jdolle: { + name: 'Jeff Dolle', + link: 'https://github.com/jdolle', + github: 'jdolle', + }, }; diff --git a/packages/web/docs/src/pages/docs/management/targets.mdx b/packages/web/docs/src/pages/docs/management/targets.mdx index 9323158a7..574d46f88 100644 --- a/packages/web/docs/src/pages/docs/management/targets.mdx +++ b/packages/web/docs/src/pages/docs/management/targets.mdx @@ -2,7 +2,7 @@ import NextImage from 'next/image' import { Callout } from '@theguild/components' import tokenImage from '../../../../public/docs/pages/guides/token.png' import newTargetFormImage from '../../../../public/docs/pages/management/new-target-form.png' -import tagetConditionalBreakingChangesImage from '../../../../public/docs/pages/management/target-conditional-breaking-changes.png' +import targetConditionalBreakingChangesImage from '../../../../public/docs/pages/management/target-conditional-breaking-changes.png' import tokenCreateSuccess from '../../../../public/docs/pages/management/target-created-token.png' # Target Management @@ -11,7 +11,7 @@ Within a Hive **project**, you can create **targets** (which are equivalent to r and manage different schemas across different contextual runtimes. When it comes to the GraphQL schema, every target is considered standalone, and can have different -states of the same schema, within the same GraphQL API project (just like different runtime +states of the same schema within the same GraphQL API project (just like different runtime environments). When a new Hive **project** is created, default targets are created (`development`, `staging` and @@ -34,15 +34,15 @@ also use the **New Target** button to create a new target. ### Conditional Breaking Changes Conditional Breaking Changes is a concept that involves marking breaking changes in your GraphQL -schemas as safe, based on real-life data and traffic reported to Hive. This is done through the +schemas as safe based on real-life data and traffic reported to Hive. This is done through the [Usage Reporting](/docs/schema-registry/usage-reporting) feature. -When a new schema of your GraphQL schema is published to the registry, Hive uses the data collected -from your API gateway to identify whether the change in your schema actually affects consumers. +When running a schema check, Hive uses the data collected from your API gateway to identify whether +the change in your schema actually affects consumers. @@ -51,15 +51,19 @@ and configure the following settings: #### Traffic Threshold and Duration -You can choose to mark a breaking change as safe, if it affects some percentage of your traffic, in -a specific time range. +You can choose to mark an incompatible change as safe, if it affects less than some amount of your +traffic in a specific time range. The threshold amount can be either a percentage of the total +traffic to that target or a fixed number of requests. Here are a few examples and their meaning: -- **Traffic Threshold:** `0%`: A breaking change is considered as breaking and dangerous if the - field was was used at least once. -- **Traffic Threshold:** `10%`: A breaking change is considered as breaking and dangerous if the - field was requested by more than 10% of all GraphQL operation. +- **Traffic Threshold:** `0 Percent of Traffic`: An incompatible change is considered as breaking + and dangerous if the field was was used at least once. This is equivalent to setting the threshold + to `1 Total Operations`. +- **Traffic Threshold:** `10 Percent of Traffic`: An incompatible change is considered as breaking + and dangerous if the field was requested by more than 10% of all GraphQL operation. +- **Traffic Threshold:** `10 Total Operations`: An inncompatible change is considered as breaking + and dangerous if the field was requested by more than 10 total requests. The maximum duration is defined by the retention of your [Hive diff --git a/packages/web/docs/src/pages/product-updates/2025-01-10-static-breaking-change-threshold.mdx b/packages/web/docs/src/pages/product-updates/2025-01-10-static-breaking-change-threshold.mdx new file mode 100644 index 000000000..5f05cd6ae --- /dev/null +++ b/packages/web/docs/src/pages/product-updates/2025-01-10-static-breaking-change-threshold.mdx @@ -0,0 +1,26 @@ +--- +title: Added a Conditional Breaking Change Static Threshold +description: + A minor improvement to our conditional breaking changes behavior that allows changes to be + considered breaking based on a minimum number of requests. +date: 2025-01-10 +authors: [jdolle] +--- + +Expect a lot of improvements to the Hive Schema Registry in 2025. + +One of the first updates this year is a small but potentially very useful option for +[Conditional Breaking Changes](https://the-guild.dev/graphql/hive/docs/management/targets#conditional-breaking-changes). +Previously, Conditional Breaking Changes checked compatibility against all operations called in the +past number of days. If the percent impacted exceeded the configured percentage threshold, then the +change would be considered breaking. Unfortunately for schemas with disproportionate operation +usage, an operation with very little percent usage could still have a major impact to their +consumers. + +To better handle this case, a new option has been added to set a static threshold for the total +number of operations that can be incompatible before the change is considered breaking. + +![Breaking Changes UI](/changelog/2025-01-10-static-breaking-change-threshold/ui.png) + +So if you were using a 0% threshold but found it a bit too restrictive, considered this new option +to set a higher static threshold.