From 8c8d1659377abe6028dd2402ce61bfafbc1d151e Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 18 Mar 2022 12:19:49 +0100 Subject: [PATCH] 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 2bfe519b898..46427f53cda 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 de67d19eaa4..381a36def7a 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)** | | | | | | | | | |