Skip to content

Commit

Permalink
docs: add change requests video (#2909)
Browse files Browse the repository at this point in the history
This change adds the change requests explainer video to the change
requests reference documentation.

As a bonus, it also cleans up some redundant whitespace.
  • Loading branch information
thomasheartman committed Jan 17, 2023
1 parent b895c99 commit 6d28cd9
Showing 1 changed file with 16 additions and 8 deletions.
24 changes: 16 additions & 8 deletions website/docs/reference/change-requests.md
Expand Up @@ -2,11 +2,22 @@
title: Change requests
---

import VideoContent from '@site/src/components/VideoContent.jsx';

:::info Availability

The change requests feature is an enterprise-only feature that was introduced in **Unleash 4.19.0**.

:::


<VideoContent videoUrls={["https://www.youtube.com/embed/ENUqFVcdr-w"]} title="Change requests in 5 minutes">

This article contains all the details about how change requests work in Unleash; but if you're only looking for a brief explanation and a demo, how about this 5 minute explainer video? 🍿

</VideoContent>


Feature flagging is a powerful tool, and because it's so powerful, you sometimes need to practice caution. The ability to have complete control over your production environment comes at the cost of the potential to make mistakes in production. Change requests were introduced in version 4.19.0 to alleviate this fear. Change requests allow you to group changes together and apply them to production at the same time, instead of applying changes directly to production. This allows you to make multiple changes to feature toggles and their configuration and status (on/off) all at once, reducing the risk of errors in production.

Our goal is developer effeciency, but we also recognize that we have users and customers in highly regulated industries, governed by law and strict requirements. Therefore, we have added a capability to change requests that will allow you to enforce the _4 eyes principle_.
Expand All @@ -19,14 +30,14 @@ Currently there are two configuration options for change requests:
* **Enable change requests** - This is a boolean value that enables or disables change requests for the project and environment.
* **Required approvals** - This is an integer value that indicates how many approvals are required before a change request can be applied. Specific permissions are required to approve and apply change requests.

The change request configuration can be set up in the project settings page:
The change request configuration can be set up in the project settings page:

![Change request configuration](/img/change-request-configuration.png)


## Change request flow

Once a change request flow is configured for a project and environment, you can no longer directly change the status of a toggle. Instead, you will be asked to put your changes into a draft. The change request flow handles the following scenarios:
Once a change request flow is configured for a project and environment, you can no longer directly change the status of a toggle. Instead, you will be asked to put your changes into a draft. The change request flow handles the following scenarios:

* Updating the status of a toggle in the environment
* Adding a strategy to the feature toggle in the environment
Expand All @@ -37,7 +48,7 @@ The flow can be summarized as follows:

![Change request flow](/img/change-request-flow.png)

Once a change is added to a draft, the draft needs to be completed before another change request can be opened. The draft is personal to the user that created the change request draft, until it is sent for review. Once changes are added to draft, the user will have a banner in the top of the screen indicating that a draft exists. The state of a change request can be one of the following:
Once a change is added to a draft, the draft needs to be completed before another change request can be opened. The draft is personal to the user that created the change request draft, until it is sent for review. Once changes are added to draft, the user will have a banner in the top of the screen indicating that a draft exists. The state of a change request can be one of the following:

* **Draft** - The change request is in draft mode, and can be edited by the user that created the draft.
* **In review** - The change request is in review mode, and can be edited by the user that created the draft. If editing ocurrs, all current approvals are revoked
Expand All @@ -47,7 +58,7 @@ Once a change is added to a draft, the draft needs to be completed before anothe

![Change request banner](/img/change-request-banner.png)

Once a change request is sent to review by the user who created it, it becomes available for everyone in the change request tab in the project.
Once a change request is sent to review by the user who created it, it becomes available for everyone in the change request tab in the project.

From here, you can navigate to the change request overview page. This page will give you information about the changes the change request contains, the state the change request is in, and what action needs to be taken next.

Expand All @@ -57,7 +68,7 @@ From here, if you have the correct permissions, you can approve and apply the ch

## Change request permissions

As a result of adding change requests, we have added three new environment specific permissions:
As a result of adding change requests, we have added three new environment specific permissions:
* Approve change request
* Apply change request
* Skip change request
Expand All @@ -69,6 +80,3 @@ Once you have created a custom project role that has the correct permissions, yo
### Circumventing change requests

In the event that you need API access to directly turn something off without going through the change request procedure, you can leverage the skip change request permission. The holder of this permission can bypass the change request procedure and directly change the feature toggle configuration, depending on the other permissions they have. The skip change request permission is only valid for circumventing the change request flow, you still need to explicitly grant the user the permissions for the actions you'd like to perform. IE: Changing a toggle status in an environment, or adding a strategy to a toggle in an environment.



0 comments on commit 6d28cd9

Please sign in to comment.