docs: update documentation around permissions for variants (#3195)

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

src/lib/features/export-import-toggles/export-import-permissions.e2e.test.ts

@@ -346,7 +346,7 @@ test('validate import data', async () => {
                     'Create context fields',
                     'Create activation strategies',
                     'Delete activation strategies',
-                    'Update variants on environment',
+                    'Update variants',
                 ],
             },
         ],

src/migrations/20230227120500-change-display-name-for-variants-per-env-permission.js

@@ -0,0 +1,22 @@
+'use strict';
+
+exports.up = function (db, callback) {
+    db.runSql(
+        `
+          UPDATE permissions SET display_name='Update variants' WHERE permission = 'UPDATE_FEATURE_ENVIRONMENT_VARIANTS';
+          UPDATE permissions SET display_name = 'Enable/disable toggles' WHERE permission = 'UPDATE_FEATURE_ENVIRONMENT';
+          UPDATE permissions SET display_name = 'Approve change requests' WHERE permission = 'APPROVE_CHANGE_REQUEST';
+          UPDATE permissions SET display_name = 'Apply change requests' WHERE permission = 'APPLY_CHANGE_REQUEST';
+          UPDATE permissions SET display_name = 'Skip change request process (API-only)' WHERE permission = 'SKIP_CHANGE_REQUEST';
+        `,
+        callback,
+    );
+};
+
+exports.down = function (db, callback) {
+    db.runSql(
+        `
+        `,
+        callback,
+    );
+};

website/docs/reference/rbac.md

@@ -82,7 +82,7 @@ You can assign the following project permissions. The permissions will be valid
 
 - **create/edit variants**
 
-  Lets the user create and edit variants within the project.
+  Lets the user create and edit variants within the project. (Deprecated with v4.21 in favor of environment-specific permissions for working with variants[^1].)
 
 ### Environment permissions
 
@@ -104,6 +104,10 @@ You can assign the following permissions on a per-environment level within the p
 
   Lets the user enable and disable toggles within the environment.
 
+- **update variants**
+
+  Lets the user create, edit and remove variants within the environment.
+
 - **approve a change request**
 
   Lets the user approve [change requests](change-requests.md) in the environment.
@@ -179,3 +183,5 @@ To enable group sync, you'll need to set two fields in your SSO provider configu
   You need to set the "Group Field JSON path" to "groups".
 
 Once you've enabled group syncing and set an appropriate path, you'll need to add the SSO group names to the Unleash group. This can be done by navigating to the Unleash group you want to enable sync for and adding the SSO group names to the "SSO group ID/name" property.
+
+[^1]: The project-level permission is still required for the [**create/overwrite variants** (PUT)](/docs/reference/api/unleash/overwrite-feature-variants.api.mdx) and [**update variants** (PATCH)](/docs/reference/api/unleash/patch-feature-variants.api.mdx) API endpoints, but it is not used for anything within the admin UI. The API endpoints have been superseded by the [**create/overwrite environment variants** (PUT)](/docs/reference/api/unleash/overwrite-feature-variants-on-environments.api.mdx) and [**update environment variants** (PATCH)](/docs/reference/api/unleash/patch-environments-feature-variants.api.mdx) endpoints, respectively.