docs: new variants per environment (#2590)

## About the changes
Documentation about feature toggle variants per environment

## Discussion points
The version when this will be available is still to be defined.

---------

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

src/lib/routes/admin-api/project/variants.ts

@@ -65,6 +65,10 @@ export default class VariantsController extends Controller {
             handler: this.getVariants,
             middleware: [
                 openApiService.validPath({
+                    summary: 'Retrieve variants for a feature (deprecated) ',
+                    description:
+                        '(deprecated from 4.21) Retrieve the variants for the specified feature. From Unleash 4.21 onwards, this endpoint will attempt to choose a [production-type environment](https://docs.getunleash.io/reference/environments) as the source of truth. If more than one production environment is found, the first one will be used.',
+                    deprecated: true,
                     tags: ['Features'],
                     operationId: 'getFeatureVariants',
                     responses: {
@@ -80,6 +84,11 @@ export default class VariantsController extends Controller {
             handler: this.patchVariants,
             middleware: [
                 openApiService.validPath({
+                    summary:
+                        "Apply a patch to a feature's variants (in all environments).",
+                    description: `Apply a list of patches patch to the specified feature's variants. The patch objects should conform to the [JSON-patch format (RFC 6902)](https://www.rfc-editor.org/rfc/rfc6902).
+                        
+                        ⚠️ **Warning**: This method is not atomic. If something fails in the middle of applying the patch, you can be left with a half-applied patch. We recommend that you instead [patch variants on a per-environment basis](/docs/reference/api/unleash/patch-environments-feature-variants.api.mdx), which **is** an atomic operation.`,
                     tags: ['Features'],
                     operationId: 'patchFeatureVariants',
                     requestBody: createRequestSchema('patchesSchema'),
@@ -96,6 +105,16 @@ export default class VariantsController extends Controller {
             handler: this.overwriteVariants,
             middleware: [
                 openApiService.validPath({
+                    summary:
+                        'Create (overwrite) variants for a feature toggle in all environments',
+                    description: `This overwrites the current variants for the feature specified in the :featureName parameter in all environments.
+
+                    The backend will validate the input for the following invariants
+
+                    * If there are variants, there needs to be at least one variant with \`weightType: variable\`
+                    * The sum of the weights of variants with \`weightType: fix\` must be strictly less than 1000 (< 1000)
+
+                    The backend will also distribute remaining weight up to 1000 after adding the variants with \`weightType: fix\` together amongst the variants of \`weightType: variable\``,
                     tags: ['Features'],
                     operationId: 'overwriteFeatureVariants',
                     requestBody: createRequestSchema('variantsSchema'),
@@ -112,6 +131,8 @@ export default class VariantsController extends Controller {
             handler: this.getVariantsOnEnv,
             middleware: [
                 openApiService.validPath({
+                    summary: 'Get variants for a feature in an environment',
+                    description: `Returns the variants for a feature in a specific environment. If the feature has no variants it will return an empty array of variants`,
                     tags: ['Features'],
                     operationId: 'getEnvironmentFeatureVariants',
                     responses: {
@@ -127,6 +148,8 @@ export default class VariantsController extends Controller {
             handler: this.patchVariantsOnEnv,
             middleware: [
                 openApiService.validPath({
+                    summary: "Patch a feature's variants in an environment",
+                    description: `Apply a list of patches to the features environments in the specified environment. The patch objects should conform to the [JSON-patch format (RFC 6902)](https://www.rfc-editor.org/rfc/rfc6902).`,
                     tags: ['Features'],
                     operationId: 'patchEnvironmentsFeatureVariants',
                     requestBody: createRequestSchema('patchesSchema'),
@@ -143,6 +166,16 @@ export default class VariantsController extends Controller {
             handler: this.overwriteVariantsOnEnv,
             middleware: [
                 openApiService.validPath({
+                    summary:
+                        'Create (overwrite) variants for a feature in an environment',
+                    description: `This overwrites the current variants for the feature toggle in the :featureName parameter for the :environment parameter.
+                        
+                        The backend will validate the input for the following invariants:
+                        
+                    * If there are variants, there needs to be at least one variant with \`weightType: variable\`
+                    * The sum of the weights of variants with \`weightType: fix\` must be strictly less than 1000 (< 1000)
+
+                    The backend will also distribute remaining weight up to 1000 after adding the variants with \`weightType: fix\` together amongst the variants of \`weightType: variable\``,
                     tags: ['Features'],
                     operationId: 'overwriteEnvironmentFeatureVariants',
                     requestBody: createRequestSchema('variantsSchema'),

src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap

@@ -6815,6 +6815,7 @@ If the provided project does not exist, the list of events will be empty.",
     },
     "/api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/variants": {
       "get": {
+        "description": "Returns the variants for a feature in a specific environment. If the feature has no variants it will return an empty array of variants",
         "operationId": "getEnvironmentFeatureVariants",
         "parameters": [
           {
@@ -6854,11 +6855,13 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "featureVariantsSchema",
           },
         },
+        "summary": "Get variants for a feature in an environment",
         "tags": [
           "Features",
         ],
       },
       "patch": {
+        "description": "Apply a list of patches to the features environments in the specified environment. The patch objects should conform to the [JSON-patch format (RFC 6902)](https://www.rfc-editor.org/rfc/rfc6902).",
         "operationId": "patchEnvironmentsFeatureVariants",
         "parameters": [
           {
@@ -6909,11 +6912,20 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "featureVariantsSchema",
           },
         },
+        "summary": "Patch a feature's variants in an environment",
         "tags": [
           "Features",
         ],
       },
       "put": {
+        "description": "This overwrites the current variants for the feature toggle in the :featureName parameter for the :environment parameter.
+                        
+                        The backend will validate the input for the following invariants:
+                        
+                    * If there are variants, there needs to be at least one variant with \`weightType: variable\`
+                    * The sum of the weights of variants with \`weightType: fix\` must be strictly less than 1000 (< 1000)
+
+                    The backend will also distribute remaining weight up to 1000 after adding the variants with \`weightType: fix\` together amongst the variants of \`weightType: variable\`",
         "operationId": "overwriteEnvironmentFeatureVariants",
         "parameters": [
           {
@@ -6964,6 +6976,7 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "featureVariantsSchema",
           },
         },
+        "summary": "Create (overwrite) variants for a feature in an environment",
         "tags": [
           "Features",
         ],
@@ -7031,6 +7044,8 @@ If the provided project does not exist, the list of events will be empty.",
     },
     "/api/admin/projects/{projectId}/features/{featureName}/variants": {
       "get": {
+        "deprecated": true,
+        "description": "(deprecated from 4.21) Retrieve the variants for the specified feature. From Unleash 4.21 onwards, this endpoint will attempt to choose a [production-type environment](https://docs.getunleash.io/reference/environments) as the source of truth. If more than one production environment is found, the first one will be used.",
         "operationId": "getFeatureVariants",
         "parameters": [
           {
@@ -7062,11 +7077,15 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "featureVariantsSchema",
           },
         },
+        "summary": "Retrieve variants for a feature (deprecated) ",
         "tags": [
           "Features",
         ],
       },
       "patch": {
+        "description": "Apply a list of patches patch to the specified feature's variants. The patch objects should conform to the [JSON-patch format (RFC 6902)](https://www.rfc-editor.org/rfc/rfc6902).
+                        
+                        ⚠️ **Warning**: This method is not atomic. If something fails in the middle of applying the patch, you can be left with a half-applied patch. We recommend that you instead [patch variants on a per-environment basis](/docs/reference/api/unleash/patch-environments-feature-variants.api.mdx), which **is** an atomic operation.",
         "operationId": "patchFeatureVariants",
         "parameters": [
           {
@@ -7109,11 +7128,20 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "featureVariantsSchema",
           },
         },
+        "summary": "Apply a patch to a feature's variants (in all environments).",
         "tags": [
           "Features",
         ],
       },
       "put": {
+        "description": "This overwrites the current variants for the feature specified in the :featureName parameter in all environments.
+
+                    The backend will validate the input for the following invariants
+
+                    * If there are variants, there needs to be at least one variant with \`weightType: variable\`
+                    * The sum of the weights of variants with \`weightType: fix\` must be strictly less than 1000 (< 1000)
+
+                    The backend will also distribute remaining weight up to 1000 after adding the variants with \`weightType: fix\` together amongst the variants of \`weightType: variable\`",
         "operationId": "overwriteFeatureVariants",
         "parameters": [
           {
@@ -7156,6 +7184,7 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "featureVariantsSchema",
           },
         },
+        "summary": "Create (overwrite) variants for a feature toggle in all environments",
         "tags": [
           "Features",
         ],

website/docs/reference/api/legacy/unleash/admin/features-v2.md

@@ -611,7 +611,15 @@ Transfer-Encoding: chunked
 
 ### Put variants for Feature Toggle {#update-variants}
 
-<ApiRequest verb="put" url="api/admin/projects/:projectId/features/:featureName/variants" title="Create (overwrite) variants for a feature toggle (example data)" payload={[
+:::caution 
+
+From 4.21 variants are tied to an environment. Check our Open API docs for the up-to-date docs: https://docs.getunleash.io/reference/api/unleash/features
+
+This endpoint affects all environments at once. If you only want to update a single environment, use [#update-variants-per-environment](#update-variants-per-environment) instead.
+
+:::
+
+<ApiRequest verb="put" url="api/admin/projects/:projectId/features/:featureName/variants" title="Create (overwrite) variants for a feature toggle in all environments (example data)" payload={[
 	{
 		"name": "variant1",
 		"weightType": "fix",
@@ -697,7 +705,15 @@ Content-Type: application/json; charset=utf-8
 
 ### PATCH variants for a feature toggle
 
-<ApiRequest verb="patch" url="api/admin/projects/:projectId/features/:featureName/variants" title="Patch variants for a feature toggle (example data)" payload={[{"op": "add", "path": "/1", "value": {
+:::caution
+
+This API documentation is no longer maintained. You should use the [OpenAPI docs for this endpoint](/docs/reference/api/unleash/overwrite-feature-variants.api.mdx) instead.
+
+This endpoint affects all environments at once. If you only want to update a single environment, use the [operation for updating variants per enviroment](/docs/reference/api/unleash/overwrite-feature-variants-on-environments.api.mdx) instead.
+
+:::
+
+<ApiRequest verb="patch" url="api/admin/projects/:projectId/features/:featureName/variants" title="Patch variants for a feature toggle in all environments (example data)" payload={[{"op": "add", "path": "/1", "value": {
   "name": "new-variant",
   "weightType": "fix",
   "weight": 200

website/docs/reference/feature-toggle-variants.md

@@ -1,23 +1,25 @@
 ---
 title: Feature Toggle Variants
 ---
-<div class="alert alert--info" role="alert">
-  <em>Feature toggle variants</em> were introduced in <em>Unleash v3.2.0</em>.
-</div>
-<br/>
+:::info Availability
+
+**Feature toggle variants** were first introduced in Unleash 3.2.
+In Unleash 4.21, variants were updated to be **environment-dependent**, meaning the same feature could have different variant configurations in different environments.
+
+:::
 
 Every toggle in Unleash can have something called _variants_. Where _feature toggles_ allow you to decide which users get access to a feature, _toggle variants_ allow you to further split those users into segments. Say, for instance, that you're testing out a new feature, such as an alternate sign-up form. The feature toggle would expose the form only to a select group of users. The variants could decide whether the user sees a blue or a green submit button on that form.
 
 Variants facilitate A/B testing and experimentation by letting you create controlled and measurable experiments. Check [our blog post on using Unleash for A/B/n experiments](https://www.getunleash.io/blog/a-b-n-experiments-in-3-simple-steps) for some more insights into how you can set it up.
 
 ## What are variants?
 
-Whenever you create a feature toggle, you can assign it any number of _variants_. This is commonly done in cases where you want to serve your users different versions of a feature to see which performs better.
+Whenever you create a feature toggle, you can assign it any number of _variants_. This is commonly done in cases where you want to serve your users different versions of a feature to see which performs better. A feature can have different variants in each of its environments.
 
 A variant has four components that define it:
 - a **name**:
 
-    This must be unique among the toggle's variants. When working with a toggle with variants in a client, you will typically use the variant's name to find out which variant it is.
+    This must be unique among the toggle's variants in the specified environment. When working with a feature with variants in a client, you will typically use the variant's name to find out which variant it is.
 
 - a **weight**: