From 5e551b01f8c3263ca8fb69657f8970abaf6d7510 Mon Sep 17 00:00:00 2001 From: Shailendra Shukla Date: Tue, 15 Mar 2022 17:44:58 -0500 Subject: [PATCH 1/5] docs: bold important text --- website/docs/addons/slack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/addons/slack.md b/website/docs/addons/slack.md index 9085e0d595..60f89f0427 100644 --- a/website/docs/addons/slack.md +++ b/website/docs/addons/slack.md @@ -38,7 +38,7 @@ Unleash Slack addon takes the following parameters. - **Slack Webhook URL** - This is the only required property. If you are using a Slack Application you must also make sure your application is allowed to post to the channel you want to post to. - **Username** - Used to override the username used to post the update to a Slack channel. - **Emoji Icon** - Used to override the emoji icon used to post the update to a Slack channel. -- Default channel - Where to post the message if the feature toggles has not overridden the channel via the slack tags. +- **Default channel** - Where to post the message if the feature toggles has not overridden the channel via the slack tags. #### Global configuration From 8c8d1659377abe6028dd2402ce61bfafbc1d151e Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 18 Mar 2022 12:19:49 +0100 Subject: [PATCH 2/5] docs: add more comprehensive overview of sdk incompatibilities --- website/docs/advanced/strategy-constraints.md | 15 +++++++++++++-- website/docs/sdks/index.md | 2 +- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/website/docs/advanced/strategy-constraints.md b/website/docs/advanced/strategy-constraints.md index 2bfe519b89..46427f53cd 100644 --- a/website/docs/advanced/strategy-constraints.md +++ b/website/docs/advanced/strategy-constraints.md @@ -6,11 +6,11 @@ title: Strategy Constraints :::info Availability Strategy constraints are available to Unleash Pro and Enterprise users. -Unleash 4.9 introduced a more comprehensive set of constraint operators. These require that both Unleash *and* your client SDK of choice support them. See the [SDK compatibility table](../sdks/index.md#server-side-compatibility-table) for more information. Prior to Unleash 4.9, the only available operators were `IN` and `NOT_IN`. +Unleash 4.9 introduced a more comprehensive set of constraint operators. These require that both Unleash *and* your client SDK of choice support them. See the [SDK compatibility table](../sdks/index.md#strategy-constraints) for more information. Prior to Unleash 4.9, the only available operators were `IN` and `NOT_IN`. ::: :::caution undefined behavior -When using _advanced strategy constraints_ (any operator that isn't `IN` or `NOT_IN`), *make sure your client SDK is up to date* and supports this feature. For older versions of the client SDKs we **cannot guarantee** any specific behavior: the constraints may evaluate to `false`, they may evaluate to `true`, or the client may raise an exception (as in the case of the **Ruby SDK** prior to **version 4.1.0**). +When using _advanced strategy constraints_ (any operator that isn't `IN` or `NOT_IN`), *make sure your client SDK is up to date* and supports this feature. For older versions of the client SDKs we **cannot guarantee** any specific behavior. Please see the [incompatibilities section](#incompatibilities) for more information. ::: **Strategy constraints** are conditions that must be satisifed for an [activation strategy](../user_guide/activation_strategy) to be evaluated for a feature toggle. @@ -176,7 +176,18 @@ If you set a context field to a value that the SDKs cannot parse correctly for a In other words: if you have a strategy constraint operator that expects a number, such as `NUM_GT`, but you set the corresponding context field to a string value, then the expression will be false: `"some string"` is **not** greater than `5`. This value can still be negated as explained in [the section on negating values](#constraint-negation). +## Incompatibilities and undefined behavior {#incompatibilities} +It's important that you use an up-to-date client SDK if you're using the advanced constraint operators introduced in Unleash 4.9. If your client SDK does not support the new operators, we cannot guarantee how it'll react. As a result, you may see different behavior across applications. + +If you use the new constraints with old SDKs, here's how it'll affect _some_ of the SDKs (the list is not exhaustive): +- The Node.js and Go client SDKs will ignore the new constraints completely: the constraints will not affect the toggle's status. +- The Python client SDK will evaluate the toggle to false, as it cannot evaluate the constraint successfully. +- The Ruby SDK raises an exception if the operator is not `IN` or `NOT_IN`. + +Please inspect the [SDK compatibility table to see which version of your preferred SDK introduced support for this feature](../sdks/index.md#strategy-constraints). + +After Unleash 4.9, we updated the client spec. Going forward, any constraint that a client does not recognize, **must be evaluated as `false`** ## [Deprecated]: Constrain on a specific environment {#constrain-on-a-specific-environment} diff --git a/website/docs/sdks/index.md b/website/docs/sdks/index.md index de67d19eaa..381a36def7 100644 --- a/website/docs/sdks/index.md +++ b/website/docs/sdks/index.md @@ -74,7 +74,7 @@ If you see an item marked with a ❌ that you would find useful, feel free to re | [Hostname](../user_guide/activation_strategy#hostnames) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | | **Category: [Custom strategies](../advanced/custom_activation_strategy)** | | | | | | | | | | | Basic support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | -| **Category: [Strategy constraints](../advanced/strategy_constraints)** | | | | | | | | | | +| **Category: [Strategy constraints](../advanced/strategy_constraints)** | | | | | | | | | | | Basic support (`IN`, `NOT_IN` operators) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | | Advanced support (Semver, date, numeric and extended string operators) | ✅ | ✅ | ✅ | ✅ | ⭕ | ⭕ | ✅ | ⭕ | | | **Category: [Unleash Context](../user_guide/unleash_context)** | | | | | | | | | | From 7e8cae3913f28305ccf81a5bd3fc52f6ecedaf25 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 18 Mar 2022 12:21:29 +0100 Subject: [PATCH 3/5] docs: change spec to specification, add link to spec --- website/docs/advanced/strategy-constraints.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/advanced/strategy-constraints.md b/website/docs/advanced/strategy-constraints.md index 46427f53cd..9c90aded1f 100644 --- a/website/docs/advanced/strategy-constraints.md +++ b/website/docs/advanced/strategy-constraints.md @@ -187,7 +187,7 @@ If you use the new constraints with old SDKs, here's how it'll affect _some_ of Please inspect the [SDK compatibility table to see which version of your preferred SDK introduced support for this feature](../sdks/index.md#strategy-constraints). -After Unleash 4.9, we updated the client spec. Going forward, any constraint that a client does not recognize, **must be evaluated as `false`** +After Unleash 4.9, we updated the [Unleash client specification](https://github.com/Unleash/client-specification). Going forward, any constraint that a client does not recognize, **must be evaluated as `false`** ## [Deprecated]: Constrain on a specific environment {#constrain-on-a-specific-environment} From 7efd30696973b13e60308ba74c902b48256ad4a4 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 18 Mar 2022 14:28:06 +0100 Subject: [PATCH 4/5] docs: link to strategy constraints from the schedule how-to guide --- website/docs/how-to/how-to-schedule-feature-releases.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/how-to/how-to-schedule-feature-releases.mdx b/website/docs/how-to/how-to-schedule-feature-releases.mdx index eed3a00b94..b5d7ac9645 100644 --- a/website/docs/how-to/how-to-schedule-feature-releases.mdx +++ b/website/docs/how-to/how-to-schedule-feature-releases.mdx @@ -27,7 +27,7 @@ This guide assumes that you've got the following: ## Schedule feature releases with strategy constraints {#strategy-constraints} -You can use this approach with _any_ strategy you want. The strategies will work just as they normally do, they just won't become active until the specified time. For example: with the standard strategy, the feature would become available to all your users at the specified time; with a gradual rollout, the rollout would start at the specified time. +[Strategy contstraints](../advanced/strategy-constraints.md#date-and-time-operators) are the easiest way to schedule feature releases. You can use this approach with _any_ strategy you want. The strategies will work just as they normally do, they just won't become active until the specified time. For example: with the standard strategy, the feature would become available to all your users at the specified time; with a gradual rollout, the rollout would start at the specified time. ### Step 1: Add an activation strategy with a date-based constraint From 0950a95698958d1eca3e959dd439354ccfeddf59 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 18 Mar 2022 14:30:02 +0100 Subject: [PATCH 5/5] docs: add a link to the SDK incompatibility section --- website/docs/how-to/how-to-schedule-feature-releases.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/how-to/how-to-schedule-feature-releases.mdx b/website/docs/how-to/how-to-schedule-feature-releases.mdx index b5d7ac9645..200f8ef533 100644 --- a/website/docs/how-to/how-to-schedule-feature-releases.mdx +++ b/website/docs/how-to/how-to-schedule-feature-releases.mdx @@ -27,7 +27,7 @@ This guide assumes that you've got the following: ## Schedule feature releases with strategy constraints {#strategy-constraints} -[Strategy contstraints](../advanced/strategy-constraints.md#date-and-time-operators) are the easiest way to schedule feature releases. You can use this approach with _any_ strategy you want. The strategies will work just as they normally do, they just won't become active until the specified time. For example: with the standard strategy, the feature would become available to all your users at the specified time; with a gradual rollout, the rollout would start at the specified time. +[Strategy contstraints](../advanced/strategy-constraints.md#date-and-time-operators) are the easiest way to schedule feature releases ([as long as your SDKs are up to date](../advanced/strategy-constraints.md#incompatibilities)). You can use this approach with _any_ strategy you want. The strategies will work just as they normally do, they just won't become active until the specified time. For example: with the standard strategy, the feature would become available to all your users at the specified time; with a gradual rollout, the rollout would start at the specified time. ### Step 1: Add an activation strategy with a date-based constraint